E se ninguém quiser documentar? Organização de documentação de microsserviços ao mínimo



Imagine que você tem uma equipe de especialistas que, de acordo com o princípio do código primeiro, constrói um sistema com muitas histórias de negócios baseadas em microsserviços. Todas as pessoas são experientes, todos têm algo a fazer além de escrever documentação ou especificações para a API desenvolvida. E todos sabem inicialmente que, se você quiser usar qual serviço, precisa examinar o código e perguntar no chat geral se algo não está claro. Situação familiar, não é? -))) E em geral está tudo bem, se a equipe não crescia com o tempo, o número de serviços e funções não aumentava, não apareciam bugs de empresas e testadores, não era necessário fornecer uma API para integração às equipes relacionadas ...



, , . .



. ? , .



  • - … . 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 .





2




All Articles