Esse é tutorial para você conhecer a ferramenta Stoplight e quais as vantagens utiliza-la em seu projeto. Todo o passo a passo descrito seguirá o exemplo do código que postei no GitHub abaixo:
thihenos/stoplight-example
Repository with some OpenApi Example and with pipeline! – thihenos/stoplight-examplegithub.co
Por que devemos documentar antes de fazer ?
Você alguma vez já se deparou com o cenário onde você precisa fazer uma compra para sua casa e acaba esquecendo de anotar os itens que você precisa e percebe que você gasta muito tempo tentando descobrir o que realmente você precisa? A sensação é horrível! Você começa a andar para um lado e para o outro, não tem certeza se está levando o que realmente precisa e o que você esperava fazer em pouco tempo, acaba se tornando numa atividade que consome muito tempo e ainda pode gerar frustração e retrabalho quando você chegar em casa.
Na indústria de software, esse tipo de situação acaba acontecendo com muita frequência com os detalhes técnicos de uma solução, onde muito das vezes são passados de forma informal ou que acabam ficando apenas com uma pessoa só. Para ajudar a solucionar esse tipo de problema, podemos utilizar uma abordagem chamada de API Design First, onde nós desenhamos e definimos coisas como: comportamento do sistema, quais suas entradas e saídas, formas de consumo, padronizações e etc. Essa abordagem trás várias vantagens, desde que a lista de itens da solução seja levada como verdade absoluta onde todas as áreas devem consultar para tirarem suas dúvidas. Com isso, uma das grandes vantagens de desenhar antes de agir, é que conseguimos garantir que várias áreas consigam andar em paralelo, como por exemplo a área de automação de testes, que já poderá implementar os testes antes mesmo do desenvolvimento concluir sua parte, se todos estiverem seguindo sempre a mesma documentação principal.
Quais as vantagens do uso do stoplight
- Além de ser uma ferramenta free para projetos com equipes enxuta
- A ferramenta suporta OpenAPI para a documentação de suas APIs
- A ferramenta suporta edição via web
- A ferramenta suporta criação de documentos markdown para documentação
Como utilizar no seu dia a dia
Primeiro, precisamos criar o nosso projeto onde iremos documentar deixar todas a documentação relacionado ao projeto. Crie sempre como CLI project para caso você queira automatizar a publicação de seus documentos usando uma pipeline.
Após criar o projeto, clique em seu nome e voilá, estaremos na pagina principal de nosso projeto, onde podemos explorar a construção dos documentos que a ferramenta suporta.
Ao clirar em API e escolher o seu nome da, a propria ferramenta apresenta um modelo de documentação de API conforme abaixo:
Para adicionar a documentação de uma nova rota, basta clicar com o botão direito em Paths e criar um novo Path da API
Modelo CLI
Caso você opte pelo modelo CLI, devemos seguir a seguinte estrutura no seu projeto├── .pipelines
├── stoplight
│ ├── docs
│ └── reference
├── stoplight.json
└── toc.json
.pipelines
Na pasta pipelines, deixei dois exemplos de script de pipelines para automatizar o processo de publicação dps arquivos do stoplight para o bitbucket ou azure devops.
stoplight
A ferramenta stoplight aceita dois tipos de arquivos para publicação, os arquivos .md e yml.
Usaremos colocaremos os.md dentro da pasta doc e todos os arquivos dentro dessa pasta representação somente uma documentação básica, como se fosse um readme.
Dentro da pasta reference colocaremos todos as definições de apis, esses arquivos deverão respeitar a definição openapi conforme o exemplo.
toc.json
Nesse arquivo, usaremos para referenciar a construção do side-bar do stoplight referenciando os arquivos criados nas pastas references ou doc
O modelo API Design First é uma boa estratégia para se adotar em protudos, pois centraliza todo seu desenvolvimento e testes pela documentação, fazendo assim, com que outras áreas envolvidas no processo de desenvolvimento da(o) API/Produto possam atuar de forma asíncrona no processo, pois todos estão sempre se baseando de uma documentação central.
Tem interesse em aprender mais sobre? Entre em contato conosco ❤️!
Referências
O que é API First Design? – Opus Software
Cada vez mais, o conceito de empresas consumirem e disponibilizarem APIs para terceiros tem criado muitas oportunidades…www.opus-software.com.br
Overview
Stoplight has an editor called Stoplight Studio, which doubles as both a Markdown editor, and a visual API Designer. An…meta.stoplight.io
OpenAPI Specification & OpenAPI Spec Design Guide
Get to know the intricate details of the all-important OpenAPI with Stoplight’s comprehensive and technical guide.stoplight.io
