OAI
Add support for "changelog" in the "info" object
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.0
title: My API Specification
changelog: 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.
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.
An alternative would be to allow external doc url to be an array with some pre-defined "types" like changelog.
As a quick fix, what about adding an x-changelog to the extension registry so that at least there is a community-specified way of representing this idea?
@dret anyone can open a PR on the extension registry (it's on the gh-pages branch). I think extensions are most likley to get approved if they're either being used in the wild or if the proposal is from someone implementing support.
On 2024-11-21 15:51, Henry Andrews wrote:
@dret https://github.com/dret anyone can open a PR on the extension registry (it's on the |gh-pages| branch). I think extensions are most likley to get approved if they're either being used in the wild or if the proposal is from someone implementing support.
That's a fair point. I may just open a PR and see if anybody supports it. If yes, that would be a good sign. If no, that's a sign as well...