You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
When maintaining an API specification, it would be really nice to offer a changelog for the API consumer. This can be as simple as a link to a changelog.
Possible Solution
The info object seems to be the most suitable place that such a parameter could be located (as an optional parameter).
Example:
info:
version: 1.1.0title: My API Specificationchangelog: https://acme.com/docs/api/v1/changelog.md
Nb: I know that this is currently possible via x- extension, yet not all tools seem to accept extensions.
The text was updated successfully, but these errors were encountered:
I support this idea. Currently, I just put a link in the description, but I think it's important enough to get a new tag and make tooling render it separately, maybe even include it if it's markdown or so.
great idea, however, i usually leverage the external doc url and point "humans" to a url that has supporting documentation of the API (and this includes a URL to a changelog)
Whether or not a "changelog" tag should support an url as value or somehow include the entire content (e.g. via markdown), is perhaps of less importance here. Both approaches are acceptable, in my opinion. The important part is to formally support and encourage stating an api's changelog.
When maintaining an API specification, it would be really nice to offer a changelog for the API consumer. This can be as simple as a link to a changelog.
Possible Solution
The
info
object seems to be the most suitable place that such a parameter could be located (as an optional parameter).Example:
Nb: I know that this is currently possible via
x-
extension, yet not all tools seem to accept extensions.The text was updated successfully, but these errors were encountered: