Creating documents using Swagger
Procedure
To create documentation for webservices using Swagger you must follow a few step:
- The class that will be documented should receive the @Api note of the package io.swagger.annotations.Api, which consists of the identification of which category the webservice is related to, for example: ticket, change request, etc.
- The identification should be put inside the @Api note, in the property tags, which will receive a value in enum ApiTagsEnum.
imagem 1
- The enum ApiTagsEnum is responsible for storing the categories the webservice has. Each enum is composed by the enum value and a Tag class instance (package springfox.documentation.service.Tag), which receives the enum value and the description of the enum.
imagem 1
- After configuring these scenarios, to actually insert the webservice documentation, you must create an interface that the webservice should implement.
imagem 1
- The interface is where the documentation will be written. These are the most used notations:
imagem 1
- The other notations are commonly used in a webservice created with spring, which will be brought to the interface and implemented on the webservice.
- To check if the documentation was created succesfully, add webmvc/swagger-ui.html# after citsmart/ on the URL.
imagem 1
- It is also possible to access the documentation of the webservice directly. Just type the webservice path on the url to see it.
imagem 1