Documentando API no Django com django-ninja

swagger-ui, django-ninja, contrato e openapi

Transcript

1. Django API & Docs swagger-ui, django-ninja, contrato e openapi Quarta 16/04 ás 20h Roger Camargo Abril 2023
2. Onde é gerado o frontend no Django?
3. templates urls.py views.py navegador
4. templates urls.py views.py FRONTEND (HTML + CSS + JS) navegador
5. Backend 🦄 Django Frontend templates navegador HTML + CSS + JS Gerado pelo Django
6. Backend 🦄 Django navegador Frontend API JSON via HTTP VueJS React Flutter React native HTML+CSS+JS Outro backend (sem front)
7. Backend Data Client 1 API System A SDK Client JS System B Client 2
8. Backend Data Client 1 API System A SDK Client JS System B Client 2 Schema API Mock Documentação de uso da API
9. Como usar sua API? Quais “endpoints”? Quais códigos de retorno? https://http.cat/
10. Backend 🦄 Django - Quais endpoints? - Quais parâmetros? - É via header, query ou body? - Qual o código de retorno? - Qual a resposta de cada endpoint? Clientes da API API JSON via HTTP
11. 201 Como documentar uma API? ✔
12. 1 Sem documentação Fetch, axios Postman Insomnia
13. 1 Sem documentação Fetch, axios Postman Insomnia 😱 Tentativa e erro
14. 1 Sem documentação 2 PDF, Markdown, DOC, Site
15. 1 Sem documentação 2 PDF, Markdown, DOC, Site ❌ Desatualizado > nada
16. 1 Sem documentação 2 PDF, Markdown, DOC, Site 3 Código gera Docs Docstrings, libs
17. 1 Sem documentação 2 PDF, Markdown, DOC, Site 3 Código gera Docs Docstrings, libs
18. 4 API design first 🎉 🎉 🎉 🎉 🎉 Uma fonte da verdade
19. 4 YAML
20. Contrato 🤝 Código Testes Documentação “Schemas” “Client” “Mock” YAML API Design First 4
21. Django Ninja https://github.com/vitalik/django-ninja 3
22. urls.py views.py DOCS usando swagger-ui
23. 👉 - Django ninja lê o código e decorators das views - Gera urls automaticamente (urls.py) - Gera documentação - Criando schema, ganhamos validação e melhor docs DOCS usando swagger-ui urls.py views.py
24. demo mostra o código
25. Conclusões: - Se sua API é apenas para uso interno, talvez tudo bem não ter documentação - Uma API documentada vai dar muito mais produtividade para todos os envolvidos, vai facilitar resolver bugs etc. - Opção 3 - É legal principalmente quando conseguimos minimizar o problema de documentação desatualizada! - Opção 4 - Contrato de API gerando tudo é outro nível, mas em sistemas legados vai dar um trabalhão. Excelente para novos projetos
26. References: https://swagger.io/resources/webinars/adopting-a-design-first-approach/ https://apisyouwonthate.com/blog/api-design-first-vs-code-first https://www.openapis.org/ https://spec.openapis.org/oas/latest.html https://www.youtube.com/watch?v=TfGHNBaK9a0 https://http.cat/ Tools: https://github.com/zalando/connexion https://openapi.tools/ https://editor.swagger.io/ https://stoplight.io/ Code sample: https://github.com/huogerac/mydjavuelist/tree/issue16_add_django_ninja_doc_api (django-ninja) https://github.com/billcode/jarless (openapi) https://github.com/confraria-devpro/hackernews-api (openapi) API Design First https://pythonpro.com.br
27. Obrigado Keep in touch @huogerac https://huogerac.hashnode.dev huogerac@gmail.com https://speakerdeck.com/huogerac