API-Documentation is done using Swagger

Acronym

sig-api-Documentation

Belongs to

SIG APIs

Responsible

FalahSama

History

(v1)   2021-01-13 - created initially

(v2)   2021-01-13 - update responsibility

(v3)   2021-01-13 - need for decision

(v4)   2021-01-13 - sources and evaluation

(v5)   2021-01-23 - updated deadline

(v6)   2021-02-01 - add Resolution

(v7)   2021-02-12 - back to 4, to be presented again with how-to

Why is there need for such a decision?

The API-documentation describes the entire API. The goal is to automatically document all API endpoints. This is achieved by using an API-Documentation tool, which will help to generate an easy API documentation source. In this way it will be easier to understand the API endpoints. This decision depends on the API style!

All teams must use the same tool to prevent differential API-documentations syntax.

Additional sources for better understanding the background

• Open API
• Code first vs. API first
• Swagger UI
• Spring Rest Docu

Viable Options

• Swagger UI
• Spring Rest Docs
• GraphQL

Alternatives not seriously considered

• Postman, not Open Source
• API Blueprint not for Java available

How is this decision evaluated?

The evaluation is a result of implemented respective tools!

when Rest is select as “sig-api-style” decision, then we will use Swaager or Spring Rest Docs. If GraphQL is chosen, so we will use the GraphQL Documentation Generator!

Resolution Details

Our team is using the tool Swagger. Swagger offers an library for our Spring-Boot Application. The tool automatically documentates API-endpoints. Therefore the documentation maintenance is heavly reduced. No further knowledge is needed, since the handling of tool is basic and easy.

Reasons for the resolution

• Automatically documentated API-endpoints
• Executable methods
• No further programming skill is needed
• Assistant tool with high usability

wiki

Mainly we choosed this resoution due to its large offers of transparent informations in contrast to Spring Rest Docs and its JSON-format.

For our code documentation, each team will need to use at least the following annotations: @Api(description = “txt”) and @ApiOperation (value = “txt”)

@Api should describe the respective rest-controller class with one sentence.

@ApiOperation should describe the respective method in the rest-controller class with a record.

More informations: Swagger Docs