Mantendo e Evoluindo REST APIs com OpenAPI Spec 3.0

Expor serviços através de REST APIs preservando a sanidade - sua e de seus utilizadores, sejam pessoas ou microserviços, internos ou externos - é uma tarefa dolorosa. Manter documentações válidas, fornecer bibliotecas para consumo da API nas linguagens necessárias e garantir a integridade das interfaces independentemente de mudanças da aplicação são atividades que exigem esforço cotidiano do desenvolvedor. Nessa talk você poderá conhecer o OpenAPI Specification (OAS) e como utilizá-lo para melhorar a Dev Experience do seu time ao projetar, manter e evoluir APIs.

Transcript

1. Isaac Pereira (@pereirazc) Mantendo e evoluindo REST APIs com OpenAPI Spec 3.0
2. Co-fundador @ Especialista em sistemas @ O que faz... Interesses... Desenvolvimento orientado a modelos Design de APIs Arquiteturas orientadas a eventos Isaac Pereira (@pereirazc)
3. “O mundo gira sobre APIs aplicativos voltados para o consumidor processos internos APIs desempenham um papel crítico - alimentando e que mantêm negócios globais funcionando State of API 2019 Report (SmartBear)
4. APIs internas 75% das organizações participantes mantém, além de suas APIs públicas, o desenvolvimento de microserviços Arquiteturas orientadas a são o motor para a proliferação de APIs internas das organizações adoção rápida Times de desenvolvimento querem ferramentas de que se adaptem as já existentes/usadas State of API 2019
5. State of API 2019 NÃO DIGA, MOSTRE
6. O dev Quem faz as APIs hello darkness my old friend...
7. Quem faz as APIs Os devs
8. 01 25 suaempresa.com.br times internos (devs) times externos (devs) SDK/Cli APIs... APIs everywhere!
9. “Uma API é antes de tudo uma interface para pessoas e máquinas
10. Frustrações do processo de desenvolvimento e integração de APIs cadê a documentação!? “ novas features na API... hora de atualizar as bibliotecas de clientes :/ “ ...aguardando o backend terminar de implementar a nova feature da API “ testes passaram... 
 O contrato da API quebra em prod anyway! “ Development Experience
11. Enterprise Applications @ Aplicações/Serviços 23 Spring Boot Rails ASP.NET Core ( , , Scala, , ...) RESTful APIs 14 Devs 16 Ruby 14 libs clientes em C# 5 libs clientes em Responsável por sistemas centrais para contratação dos serviços, cobrança e atendimento de clientes {
12. Source of Truth Especificação de API Clientes/ SDK Docs Testes de Contrato Mocks e prototipação Stubs de Backend
13. WSDL WADL 2001 2009 2011 2013 2015 2017 graphql.io Swagger OAS v3.0 Formatos de Especificação de API grpc.io raml.org api-blueprint.org
14. OpenAPI Specification servers security tags externalDocs info paths components schemas responses parameters examples requestBodies headers links securitySchemes callbacks OpenAPI Initiative v3.0.2 OAI/OpenAPI-Specification & : 100.000 download/dia de ferramentas do ecossistema Sonatype npm YAML JSON Descrito em ou humans computers ... defines a standard, programming language-agnostic interface description for REST APIs, which allows both and to discover and understand the capabilities of a service (...) “
15. OpenAPI Specification 3.0 servers security tags externalDocs info paths "3.0.0" Swagger Petstore | A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification Swagger API Team apiteam@swagger.io Apache ... openapi: info: version: 1.0.0 title: description: termsOfService: http://swagger.io/terms/ contact: name: email: url: http://swagger.io license: name: 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.htm components schemas responses parameters examples requestBodies headers links securitySchemes callbacks
16. OpenAPI Specification 3.0 servers security tags externalDocs info paths "3.0.0"
 ... []
 ... http bearer JWT openapi: security: - JWTAuth: components: securitySchemes: JWTAuth: type: scheme: bearerFormat: components schemas responses parameters examples requestBodies headers links securitySchemes callbacks
17. OpenAPI Specification 3.0 servers security tags externalDocs info paths components schemas responses parameters examples requestBodies headers links securitySchemes callbacks components components components paths: post: description: operationId: requestBody: description: required: true content: schema: responses: description: content: schema: ... /pets: Creates a new pet in the store. addPet Pet to add to the store application/json: $ref: '#/ /schemas/NewPet' '200': pet response application/json: $ref: '#/ /schemas/Pet' '401': $ref: '#/ /responses/Unauthorized'
18. OpenAPI Specification 3.0 servers security tags externalDocs info paths components schemas responses parameters examples requestBodies headers links securitySchemes callbacks components components: responses: Unauthorized: description: schemas: Pet: allOf: - type: required: properties: id: type: format: NewPet: type: required: properties: name: type: tag: type: ... Access token is missing or invalid - $ref: '#/ /schemas/NewPet' object - id integer int64 object - name string string
19. https://openapi.tools Redocly/redoc ReDoc Documentation and exploration swagger-api/swagger-ui Swagger UI Documentation and exploration OpenAPITools/openapi-generator OpenAPI Generator Client/SDK generation interagent/commitee Committee Request/Response validation stoplightio/prism Prism Mock server apiaryio/dredd Dredd Contract-based testing
20. Pipeline de Desenvolvimento Especificação de API Clientes/ SDK Docs Testes de Contrato Mocks e prototipação Stubs de Backend
21. Ciclo de Desenvolvimento de API
22. Como nascem as APIs Code-first Contract-first internas Maioria das APIs nasce assim SSOT Especificação nasce como ( ) SSOT Pode convergir para especificação OpenAPI como single source of truth ( ) eventualmente no código guiam a criação da spec Tag/anotações requests/responses Validação de reforçada na API em fase de desenvolvimento
23. especificação antes de tudo fluxo desenvolvimento Mova o foco do desenvolvimento das suas APIs para a e construa e seu a partir disso padrão ferramentas do ecossistema Adote um e explore as ao máximo spec Use o ponto de vista que a te dá para criticar e melhorar a sua API Guarde no coração...
24. Obrigado!