Does Open API 3.0 specification support changelogs?

Question

I am using Open API 3.0 specification to document my APIs.

I have observed that Open API 3.0 has a version attribute. I was wondering if it had a way to document changelogs. Or do just use the externalDocs attribute ?

Answer 1

Changelogs are not a built in feature of the specification but the version field definitely helps as the basis for generating them. I've got a GitHub action that does a "release" on GitHub when a specification version number changes (which is does for every change we make) so the releases page becomes our changelog. The data can also be taken from the releases (available via GitHub API).

As for pointing to a changelog - externalDocs is probably a good way to do it.