O documento discute a importância da documentação de APIs, incluindo o propósito da documentação de API, fatores considerados na escolha de uma API e benefícios de uma boa documentação. Ele fornece dicas sobre como documentar APIs de forma eficaz, como usar linguagem acessível e padronização, e contratar um escritor técnico.

1. Dendicasa

2. Dendicasa

3. Sua API está bem
documentada?
Tainara Reis

4. Quem Sou
● Consultora de Qualidade na Thoughtworks
● Criadora de Conteúdo sobre Qualidade @qatainarareis
● Engenheira de Software pela Universidade de Brasília
● MBA em Gestão da Qualidade
Sua foto aqui!
Tainara Reis

5. Qual o propósito da documentação da API?
➔ Explica o que ela faz
➔ Apresenta as regras de negócio
➔ Explica como ela deve ser usada
➔ O que esperar quando ocorre um
erro
➔ Quais credenciais de segurança
usar
Fonte: petstore.swagger.io/

6. Quão bem
documentada
estava a última
documentação
de API que
leu?
Bem documentada
Razoável
Mal documentada

7. O que a comunidade diz a respeito?
A nota média para
a documentação
foi de 5.06
Fonte: Obstacles to Consuming APIs, State of the API Report 2020 by Postman
Para 60% o
conhecimento
sobre as APIs foi
obtido através da
documentação
Para 70% a
documentação é
um fator
considerado ao
escolher uma API
para integrar

8. Fonte: Obstacles to Consuming APIs, State of the API Report 2020 by Postman

9. Fonte: SmartBear API State of Art 2020
Tópicos
mais
desejados

10. Boas práticas
Use
linguagem
acessível
Adote
padronização
Planeje a
distribuição e
discovery
Promova
versionamento
Aprenda com
bons exemplos
Adote o Spec
Driven
Development
Contrate uma
pessoa tech
writer

11. Benefícios
alcançados
Facilidade ao realizar
testes de contrato
Onboarding mais rápido
Melhor experiência
das usuárias
Aumento na adoção da API

12. Leia o artigo na íntegra
bit.ly/tainaraDTAR

13. @qatainarareis
trakto.link/qatainarareis
Dúvidas?