I found this project https://github.com/OAI/OpenAPI-Specification
As I understood we can write documentation in
.json files. Just pass the YAML/JSON file to a server running the Swagger UI and Swagger UI will dynamically generate beautiful documentation from those Swagger-compliant APIs. The petstore example should give you the idea.
You can use a build engine (CI/CD server or whatever) like Jenkins to automate the documentation publishing process. For example, each REST API repository should provide at least one of these
.json files (which by the way are generated by the Swagger Editor). Then after each push to that repository, Jenkins will get those
.json files and upload them to your Documentation server where the Swagger UI is up and running.
REST API developers can share the API documentation link with client developers and also be confident that each change in the
.json files will be reflected in the documentation. They just need to push the changes. Since you need to maintain those Swagger-compliant APIs, I personally suggest to use the
.yml file, simply because it's more readable.