Swagger2 with Springboot. How to separate documentation from source code?

Question

Good afternoon, you guys.

I’m documenting the Apis of a Spring Boot project using Swagger2.

There are two ways to document: using a text file (JSON or YML) or using annotations. The problem of using a text file is the difficulty in maintaining it, because the file will get bigger and bigger, already using annotations ends up polluting the source code.

Does anyone know if there is a way to create a second project with just the documentation? In this way it would be possible to separate the documentation from the source code.

Answer 1

Swagger has a verbiage structure for writing contracts. Strategies that aim to focus on designing the API (First API) view create a repository to carry out API design, usually writing in YAML format (more streamlined).

From the contract drawn use a Swagger-codegen tool to generate project scaffolding.

The strategy would be to focus on an automation born from the contract where scaffolding, sandbox and Swagger-ui are generated and made available already for consumption.

If you want another alternative to write a contract with a less verbose RAML (Restful API Modeling Language) is interesting. The disadvantage of RAML is when to its available tooling compared to Swagger.

Answer 2

As far as I know there are the two ways you quoted.

1 - Adding the Swagger dependency to the pom.xml of your Spring Boot project;

2 - Creating a YAML/JSON file and using it in an external tool(Mulesoft has a very good YAML/RAML editor);

Another alternative(I think it’s not too trivial) is that you could create a class if you set up in another Spring boot project and document everything there, and this "documentation" project is a dependency to be noted in your project’s pom.xml, but I don’t think it’s usually this practice.