provide API versions history

[adam-lipovsky]

Hi there

I found usefull to give a info about actual version and some brief history to an API consumer. Now, every API module has endpoints /watchdog, /openapi and /versions. GET /versions gives json which looks like this:

{
  "module": "registration",
  "version": "1.2.1",
  "history": [
    {
      "version": "1.2.1",
      "date": "2025-08-14T14:03:04",
      "description": "* endpoint GET \"/aml-options\" extended with non-mandatory query param \"option\". If empty, all options are returned"
    },
    {
      "version": "1.2.0",
      "date": "2025-07-17T09:11:10",
      "description": "* endpoint GET \"/aml-options\" - added fields \"items_src\" and \"items_map\" if source is external\n  * \"items_src\" - link to external items source\n  * \"items_map\" - json with mapping between external source and aml-options item list structure"
}

Description is formated in markdown.

This code is (like /openapi) dynamicaly generated. So the advantage of giving an API consumer info about history and actual changelist lays in the fact that the developer knows anytime what he/she is working with and if required feature is already implemented or not.

---

The problem: what is best way to include these informations in openapi documentation? Something like the dev opens Swagger and see it formated. I know about extensions (like including this json in "x-api-history"), but these are ignored by Swagger and there has to be some Swagger plugin development. Doesn't exist something like that nowadays? Or what do you see as preferable solution?

Thanks for advices and have a fine day :)

Adam L.

[ralfhandl]

Swagger UI is a different project maintained at https://github.com/swagger-api/swagger-ui. You might want to ask your question there.

This repo is for maintaining and evolving the tool-independent OpenAPI specification.

Thanks!