Migrate away from swagger-cli

Why

The tool we use to build the API-Specs (swagger-cli) is no longer being actively developed:

This repository has been archived by the owner on Aug 18, 2023. It is now read-only.

Source: https://github.com/APIDevTools/swagger-cli

Using software that is no longer actively developed is a bad practice (unless its feature complete but even then, you need dependency updates).

Relevante Links und Bemerkungen

• We're currently using an (up-to-date) fork of swagger-cli tool for reasons outlined in the Makefile
• Current usages of swagger-cli: see comments
• Redocly CLI looks good, relevant links:
  • https://redocly.com/docs/cli/installation/
  • https://redocly.com/docs/cli/guides/migrate-from-swagger-cli/
  • https://apisyouwonthate.com/blog/redocly-cli/

Alternativen?

Meine Recherchen haben keine praktikable Alternative zu redocly-cli ergeben. Es gibt schlicht keine aktuellen und kontinuierlich gewarteten Tools in diesem Bereich. Einzig UI/IDEs scheinen einen gewissen Funktionsumfang (Swagger Editor, OpenAPI Generator, etc.) abzudecken. Uns geht es aber primär um das bundling im CI Umfeld - dies bietet nur redocly im vollen Umfang.

Davon abgesehen ist der Migrationspfad von swagger-cli zu redocly sauber dokumentiert und recht kurz & einfach.

Akzeptanzkriterien

1. Evaluate a tool that can bundle / build / verify an API-Spec other than swagger-cli for nor more than ~4h
2. No FIT-Connect tooling uses swagger-cli anymore but another tool
3. All created artifacts (submission-api, docs, self-service-api) are semantically equivalent (tool to build the spec doesen't change the spec)
4. Project https://git.fitko.de/fit-connect/swagger-cli/ is archived.