Imagine that you have a team of specialists who, according to the code-first principle, make a system with many business stories based on microservices. All people are experienced, everyone has something to do besides how to write documentation or specifications for the developed API. And everyone initially knows that if you wanted to use which service, you need to look into the code and then ask in the general chat if something is not clear. A familiar situation isn't it? -))) And in general, everything is fine, if the team did not grow over time, the number of services and functions did not grow, bugs from businesses and testers did not appear, it was not required to provide an API for integration to related teams ...
, , . .
. ? , .
- - … . Confluence.
- - Jira .
- , . .
- , , - — Jira
? . . :
- - ( Jira)
- ( , REST json DTO, .
- , REST .
, contract-first , . , , .
TO-DO . . , . . — .
- « »
- ,
- "Single source of true"
:
- Readme.md — , .
- REST Swagger. Swagger Hub
- ,
- Jira , . Jira — Component
- , Readme.md
. . .
Gitlab
Readme.md
Readme.md — . « ». ( ) :
- ?
- ?
- ? ?
- ?
- ?
- ? ? ?
- ?
Readme .md , . , « », .
Swagger REST
Swagger REST REST . Swagger Hub REST. , , , API .
Swagger . . REST , , .
, /src. .
, /doc, . , AsciiDoc (https://asciidoc.org/) PlanUML (https://plantuml.com/).
DAO, JPA REST. .
Jira
Jira — , . Jira , . , .
Jira , , Jira , , ( ) .
"" Jira Jira . . , , .
Jira :
- — . , , . .
- —
- ( ) — , , . ,
Confluence
Service Report ( ) — . — , Readme.md.
Gitlab, Readme.md. , , Gitlab
Swagger Hub
Swagger Hub REST Swagger .