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

Question

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

Navigation

#1 by (0 votes)
#2 by (0 votes)

0

Good afternoon, guys.

I am 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, 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? This way it would be possible to separate the documentation from the source code.

java spring-boot swagger

asked by anonymous 24.10.2017 / 19:52

2 answers

How to allow login in the system validating user and password by the database in php? Function that shows list in reverse order

score 0 · Answer 1

As far as I know, there are two ways you mentioned.

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

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

Another alternative (I think it's not very trivial) is that you could create a class if setting in another Spring boot project and document everything there, and this "documentation" project being a dependency to be annotated in pom.xml of your project, but I do not think that practice is customary.

score 0 · Answer 2

The swagger has a verbal structure for writing contracts. Strategies that focus on the design of the API (API First) vision create a repository to perform the drawing of the API, usually writing in the YAML (leaner) format.

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

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

If you want another alternative to writing a contract with a less verbal pattern, the RAML (RESTful API Modeling Language) is interesting. The disadvantage of RAML is when it comes to its available tooling relative to swagger.