Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Modelando APIs com a OpenAPI Specification

Modelando APIs com a OpenAPI Specification

A modelagem de APIs é algo crucial no projeto de um software. É a partir dela que as equipes de desenvolvimento e de testes começarão a construir o software e os cenários de testes. Contudo, contratos mal definidos podem levar a erros no momento da integração e/ou durante os testes. O objetivo desta palestra é mostrar como a modelagem de APIs é importante para a criação de contratos bem definidos e como a OpenAPI Specification auxilia na descrição de APIs que podem ser compreendida por todos os atores envolvidos e funcionando como "fonte única da verdade". A utilização da OpenAPI Specification traz inúmeros benefícios como a geração de uma documentação interativa entre outros.

52711e2157a6fed933b0361cc06a6953?s=128

Marcel dos Santos

June 17, 2021
Tweet

Transcript

  1. Marcel Gonçalves dos Santos @marcelgsantos OpenAPI Specification modelando APIs com

    a
  2. pensandonaweb.com.br desenvolvedor web full-stack Marcel Gonçalves dos Santos @marcelgsantos

  3. @phpsp phpsp.org.br

  4. Interaja nas mídias sociais!
 
 - fale sobre o evento,

    palestrantes e conteúdo - tire fotos do evento e publique
 - interaja com outros participantes do evento - tire dúvidas ou dê feedbacks para os palestrantes
  5. 1. seguir @marcelgsantos no Twitter
 2. tuitar utilizando as hashtags

    #OpenAPI e #TheDevConf e me marcar no tweet
 3. não vale tuíte em branco
 4. não vale retuíte Concorra a um livro da Casa do Código! 🤩
  6. A onipresença das APIs no mundo moderno

  7. as APIs são onipresentes nos dias atuais e estão presentes

    na maioria das tarefas que fazemos no dia-a-dia
  8. exemplo 01 ver as notícias no início do dia pelo

    celular, pedir um carro por aplicativo, realizar uma transferência bancária via PIX ou fazer uma compra online
  9. as APIs são a "cola digital" que permitem acelerar parcerias,

    facilitar a integração entre aplicações e criar novos negócios
  10. exemplo 02 uma API para calcular a distância entre dois

    locais ou uma API que compara o preço de um produto nas maiores lojas do mercado
  11. exemplo 03 criar um novo negócio que permite listar os

    pratos em promoção nos restaurantes da região via API
  12. O que é uma API REST?

  13. uma API é um conjunto de definições e protocolos usado

    no desenvolvimento e integração de software de aplicações
  14. uma API permite a comunicação entre aplicações sem precisar saber

    como elas foram implementadas
  15. REST significa Representational State Transfer é um estilo arquitetural criado

    por Roy Fielding
  16. o REST são um conjunto de boas práticas denominadas restrições

    e é baseado no protocolo HTTP
  17. ele utiliza as funcionalidades do protocolo como o conceito de

    URIs, verbos, cabeçalhos, status code e media types
  18. uma API RESTful é aquela que está em conformidade com

    os conceitos REST
  19. O que é a OpenAPI Specification?

  20. a OpenAPI Specification é uma especificação aberta e guiada pela

    comunidade utilizada para a descrição de APIs
  21. a OpenAPI Specification faz parte da OpenAPI Initiative e se

    originou a partir da Swagger specification
  22. a OAS é agnóstica de linguagem de programação e é

    compreensível por seres humanos e máquinas
  23. a partir da especificação pode-se gerar, por exemplo, uma documentação

    interativa, boilerplate de código e casos de testes
  24. um documento OpenAPI pode descrever uma API nos formatos YAML

    ou JSON
  25. os documentos podem ser criados manualmente ou dinamicamente através de

    uma aplicação (utilizando annotations, por exemplo)
  26. somentes os serviços REST podem ser descritos pela OpenAPI Specification,

    isto é, nem todos os serviços HTTP podem ser descritos
  27. a OAS não força um processo de desenvol- vimento e

    as abordagens conhecidas são a design-first e a code-first
  28. Porque modelar ou descrever uma API REST utilizando a OAS?

  29. as APIs são um elemento crucial na construção de aplicações

    nos dias atuais
  30. são através delas que o front-end de uma aplicação se

    comunica com o back-end…
  31. …ou que uma aplicação se comunica com outra aplicação

  32. é por esse motivo que modelar e descrever uma API

    é tarefa importante para diversos atores como desenvolvedores back-end, front-end e testers
  33. mas acontecem situações como:
 
 A: Quais serão os dados

    retornados pela API de pedidos? B: Os dados serão id, cliente, itens, valor total e status. A: Ok, vou implementar a minha parte. B: Ok, vou implementar a minha parte também.
  34. None
  35. isso pode ocasionar problemas como:
 
 - problema ao integrar

    o front-end e back-end
 - incompatibilidade de tipos do payload
 - payload de erro não padronizado
 - esquecer de tratar status code não previstos
  36. para evitar estes tipos de problemas reco- menda-se utilizar a

    abordagem design-first
 para modelar e descrever APIs
  37. a abordagem design-first permite planeja- mento prévio e compreensão robusta

    entre desenvolvedores e especialistas de domínio de como a API deve funcionar
  38. ela permite também a utilização da linguagem ubíqua do domínio

    para modelar a API, isto é, utilizá-la em urls, query strings, payloads e mensagens de erro
  39. e ao descrever a API utilizando a OpenAPI Specification tem-se

    uma linguagem comum entre os vários atores envolvidos
  40. a OAS pela sua facilidade de leitura para humanos e

    máquinas torna-se a fonte única da verdade na descrição de APIs
  41. além disso pode-se gerar automaticamente, por exemplo, uma documentação interativa,

    boilerplate de código e casos de testes
  42. Caso de Uso
 API para gerenciamento
 de palestras

  43. criar uma API REST para o gerenciamento de palestras de

    um evento de tecnologia
  44. uma palestra deverá ser associada a um palestrante e ter

    os campos: título, descrição, nível, duração, data e horário e se possui live coding
  45. !// GET /talks/5049c8b4-4e46-4a41-b52e-83ef8a315a76
 { "id": "5049c8b4-4e46-4a41-b52e-83ef8a315a76", "speaker_id": "7a728c56-b966-4dcc-adc5-57c0f807392c", "title": "Modelando

    APIs com a OpenAPI Specification", "description": "A modelagem de APIs é algo crucial no…”, "level": "beginner", "duration": 30, "presentation_date": "2021-06-08 11:30", "live_coding": true }
  46. é possível filtrar as palestras por nível, data de apresentação

    e se possui live coding
  47. !// GET /talks?level=beginner&date=2021-06-08&live_coding=true
 [ { "id": "5049c8b4-4e46-4a41-b52e-83ef8a315a76", "speaker_id": "7a728c56-b966-4dcc-adc5-57c0f807392c", "title":

    "Modelando APIs com a OpenAPI Specification", "description": "A modelagem de APIs é algo crucial no!!...", "level": "beginner", "duration": 30, "presentation_date": "2021-06-08 11:30", "live_coding": true } ]
  48. não é o objetivo da palestra ensinar sobre boas práticas

    ou design de APIs
  49. para isso, deixo como referência as ótimas palestras do Kleber

    Bacilli e do Thiago Lima
 
 - Design de APIs RESTful - youtu.be/psLrAsdHltQ
 - REST API com Thiago Lima - youtu.be/59iOK5TE2CY
  50. Modelando uma API REST utilizando a OpenAPI Specification

  51. um documento OpenAPI pode ser composto por um único ou

    vários arquivos
  52. recomenda-se que o documento raiz tenha o nome openapi.yaml ou

    openapi.json
  53. um documento OpenAPI que descreve uma API REST deve ter

    obrigatoriamente os campos openapi, info e paths
  54. openapi - indica a versão da especificação
 info - possui

    informações gerais como título, descrição e versão da API
 paths - permite descrever os entrypoints da API
  55. exemplo 06 um documento OpenAPI mínimo

  56. openapi: 3.0.1 info: title: A minimal OpenAPI document version: 0.0.1

    paths: {}
  57. exemplo 07 modelagem inicial do caso de uso

  58. openapi: 3.0.1 info: title: The Developer's Conference API description: API

    para o gerenciamento de palestras do TDC contact: name: Marcel dos Santos url: http:!//example.com/support email: marcelgsantos@gmail.com version: 0.1.0 paths: {}
  59. pode-se utilizar ferramentas especializadas para a descrição e modelagem de

    APIs como o Swagger Editor e o Stoplight
  60. contudo, pode-se utilizar também um editor de texto como o

    VSCode ou uma IDE como o IntelliJ ou PhpStorm
  61. exemplo 08 preview da modelagem inicial do caso de uso

  62. None
  63. o campo servers permite descrever um ou mais servidores de

    uma API
  64. exemplo 09
 descrição dos servidores disponíveis no caso de uso

  65. servers: - url: http:!//api-dev.example.com description: Development Server - url: https:!//api-hmg.example.com

    description: Homolog Server - url: https:!//api.example.com description: Production Server
  66. None
  67. o campo paths é onde são descritos os endpoints e

    suas operações
  68. um path deve começar com uma barra / e pode

    utilizar placeholders para valores como, por exemplo, /talks/{uuid}
  69. ele é concatenado com url do servidor para construir a

    url completa
  70. um path possui campos fixos que representam as operações como

    get, 
 post, put e delete
  71. as operações podem ter os campos summary, description, tags, operationId

    que são responsáveis por descrever, organizar e identificar as mesmas
  72. exemplo 10
 modelagem dos paths e operações do caso de

    uso
  73. paths: /talks/{uuid}: put: summary: altera os dados de uma palestra

    operationId: updateTalk tags: - talks parameters: # !!... requestBody: # !!... responses: # !!...
  74. e também podem ter os campos parameters, requestBody e responses

    que permitem definir os parâmetros, o corpo da requisição e as respostas
  75. o campo parameters pode ter os campos name, in, description

    e required e permite descrever os parâmetros que estão na url, query string, cabeçalho ou cookie
  76. exemplo 11
 modelagem dos parâmetros de uma requisição do caso

    de uso
  77. paths: /talks/{uuid}: put: summary: altera os dados de uma palestra

    operationId: updateTalk parameters: - name: uuid in: path description: uuid da palestra required: true schema: type: string format: uuid requestBody: # !!... responses: # !!...
  78. o campo requestBody possui os campos fixos description, content e

    required e permite descrever o corpo da requisição
  79. o campo content é obrigatório e a sua chave refere-se

    a um media type como application/json e o seu valor a um media type object
  80. exemplo 12
 modelagem do corpo da requisição do caso de

    uso
  81. paths: /talks/{uuid}: put: summary: altera os dados de uma palestra

    operationId: updateTalk parameters: # !!... requestBody: description: corpo da requisição required: true content: application/json: schema: $ref: '#/components/schemas/Talk' responses: # !!...
  82. o campo responses possui chaves que representam os status code

    possíveis para a resposta
  83. e cada status code possui os campos description e content

    e permite descrever o corpo da resposta
  84. exemplo 13
 modelagem do corpo da resposta do caso de

    uso
  85. paths: /talks/{uuid}: put: summary: altera os dados de uma palestra

    operationId: updateTalk parameters: # !!... requestBody: # !!... responses: '200': description: Ok '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/DomainError'
  86. um schema permite definir tipos de dados e podem ser

    objetos, primitivos ou arrays
  87. ele pode ser utilizado para definir o tipo de dados

    de um parâmetro, corpo de requisição ou corpo de resposta
  88. exemplo 14
 utilização de um schema para definir um tipo

    de um parâmetro do caso de uso
  89. paths: /talks: get: summary: listar palestras parameters: - name: level

    in: query description: nível da palestra required: false schema: type: string enum: - beginner - intermediate - advanced
  90. pode-se criar schemas mais complexos e que podem ser reutilizados

    em várias partes da documentação
  91. exemplo 15
 criação de um schema para ser reutilizado do

    caso de uso
  92. components: schemas: Talk: type: object properties: id: type: string format:

    uuid speaker_id: type: string format: uuid title: type: string description: type: string level: type: string type: string description: type: string level: type: string enum: - beginner - intermediate - advanced duration: type: integer format: int32 presentation_date: type: string format: datetime has_live_coding: type: boolean
  93. None
  94. Conclusão

  95. a descrição e modelagem de APIs utilizando a abordagem design-first

    é importante…
  96. …para que todos os atores envolvidos façam o planejamento antecipado

    e tenham uma compreensão robusta sobre a API
  97. ela permite com que possíveis erros sejam antecipados e efeitos

    indesejados sejam evitados como problemas na integração
  98. a OpenAPI Specification funciona como linguagem única para a descrição

    de APIs REST e é facilmente legível por humanos e máquina
  99. isso faz com que o documento OpenAPI se torna a

    fonte única da verdade sobre a API na sua aplicação
  100. além de permitir a geração automática de boilerplate de código,

    documentação interativa ou casos de testes
  101. essa apresentação apenas arranhou a superfície quando se fala da

    OAS e suas possibilidades
  102. recomenda-se aprofundar os estudos para entender melhor os detalhes da

    OAS como media types, recursos de segurança e schemas mais complexos
  103. vá em frente e divirta-se!

  104. Referências

  105. bit.ly/palestra-openapi-specification

  106. Avalie!

  107. @marcelgsantos speakerdeck.com/marcelgsantos Obrigado. Perguntas?