-
Notifications
You must be signed in to change notification settings - Fork 9.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Linking API to OpenAPI and documentation #724
Comments
I think this would be an excellent feature. I have an use case in mind wherein having this sort of resource would be useful. |
@dret We've discussed the use of described-by before to link an API to an OpenAPI description. Do you see service-desc as being more suited for this scenario? |
On 2016-07-04 15:58, Darrel wrote:
i am certainly biased because i have cooked up the "service-desc" and "described-by" seems a bit odd to me in this case because it seems to be "The relationship A describedby B asserts that resource B provides a in the end, all the link relation types have fuzzy definitions that |
On 2016-07-04 13:03, Ed Skoviak wrote:
strictly speaking this would just be a best practice and not an actual |
@darrelmiller I agree with @dret here – |
only positive feedback so far. i take that as a form on encouragement. ;-) |
So, I think this is a weird request. Something like, |
On 2016-07-05 18:34, Warren Parad wrote:
could you elaborate a bit? i don't think i quite get what you're saying
again, please elaborate on that a little bit. what's the connection |
@dret, you bring up some interesting points. Most noteworthy I would add though is fundamentally hypermedia provides the mechanism for self-discoverable APIs. I have found Google's similar thing with instructions, but I tempted to believe that this documention should be available from a human readable source, a wiki, developer docs, etc... What would be the use case to have something like this? |
On 2016-07-05 20:10, Warren Parad wrote:
to have something like what? do you mean the links that i propose in i am afraid i still don't quite understand your concerns. are you |
Aren't full APIs discoverable from their documentation, I.e. your service wiki or client homepage/portal. Is that not what service owners are doing? Are some teams doing something that makes no sense? |
i don't know the answer to that question. but i don't think it matters for this issue. this issue is about how to discover service description/documentation from resources, not the other way around. |
Isn't the recommendation is always use link relations where appropriate?
Especially type and self, others as it makes sense. I'm not sure how
useful the ones in the rfc you created are, although I suppose someone
could find a use, but either way, why call them out in the Open API
specification?
|
@wparad What @dret is suggesting is to use link relations. That what |
On 2016-07-07 21:04, Warren Parad wrote:
the proposal of this issue is to recommend to make OpenAPI descriptions |
first stab at #734, any feedback greatly appreciated. thanks! |
is there anything i can do to help moving this issue forward? thanks! |
See also the schema.org WebAPI type, where the documentation property can point to an OpenAPI definition. |
just wondering: this does not seem to have made it into 3.0. is there anything i can do to help? it would be great to see that there is a recommended way of linking an API to its OpenAPI spec. |
On 2017-05-31 13:47, Ron wrote:
@dret <https://github.com/dret> I'm afraid not. We're feature complete
for 3.0 and try mostly to deal with fixes. We have marked your PR <#734>
as post 3.0 for future consideration.
just to be clear: this is not a feature request. it's something that you
could call "best practice" or whatever other term you might have for
non-binding guidance in the spec.
a bit sad that it got silently dropped on the floor.
|
Does it make sense to revive this issue for maybe add discoverability guidance to whatever the next OpenAPI version is? |
would it make sense to recommend best practices for how an API should make its OpenAPI description (and potentially additional documentation) discoverable? we don't know how exactly an API is designed, but if it uses/supports hypermedia, we could recommend to use the link relations proposed here: https://tools.ietf.org/html/draft-wilde-service-link-rel
we might add text such as:
i'd be more than happy to make a PR to that effect, but first wanted to raise an issue and discuss it.
The text was updated successfully, but these errors were encountered: