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.

Marcel dos Santos

June 17, 2021
Tweet

More Decks by Marcel dos Santos

Other Decks in Programming

Transcript

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

    View Slide

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

    View Slide

  3. @phpsp
    phpsp.org.br

    View Slide

  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

    View Slide

  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!
    🤩

    View Slide

  6. A onipresença das APIs
    no mundo moderno

    View Slide

  7. as APIs são onipresentes nos dias atuais e
    estão presentes na maioria das tarefas que
    fazemos no dia-a-dia

    View Slide

  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

    View Slide

  9. as APIs são a "cola digital" que permitem
    acelerar parcerias, facilitar a integração
    entre aplicações e criar novos negócios

    View Slide

  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

    View Slide

  11. exemplo 03
    criar um novo negócio que permite listar os
    pratos em promoção nos restaurantes da
    região via API

    View Slide

  12. O que é uma
    API REST?

    View Slide

  13. uma API é um conjunto de definições e
    protocolos usado no desenvolvimento e
    integração de software de aplicações

    View Slide

  14. uma API permite a comunicação entre
    aplicações sem precisar saber como elas
    foram implementadas

    View Slide

  15. REST significa Representational State
    Transfer é um estilo arquitetural criado por
    Roy Fielding

    View Slide

  16. o REST são um conjunto de boas práticas
    denominadas restrições e é baseado no
    protocolo HTTP

    View Slide

  17. ele utiliza as funcionalidades do protocolo
    como o conceito de URIs, verbos,
    cabeçalhos, status code e media types

    View Slide

  18. uma API RESTful é aquela que está em
    conformidade com os conceitos REST

    View Slide

  19. O que é a OpenAPI
    Specification?

    View Slide

  20. a OpenAPI Specification é uma especificação
    aberta e guiada pela comunidade utilizada
    para a descrição de APIs

    View Slide

  21. a OpenAPI Specification faz parte da
    OpenAPI Initiative e se originou a partir da
    Swagger specification

    View Slide

  22. a OAS é agnóstica de linguagem de
    programação e é compreensível por seres
    humanos e máquinas

    View Slide

  23. a partir da especificação pode-se gerar, por
    exemplo, uma documentação interativa,
    boilerplate de código e casos de testes

    View Slide

  24. um documento OpenAPI pode descrever
    uma API nos formatos YAML ou JSON

    View Slide

  25. os documentos podem ser criados
    manualmente ou dinamicamente através
    de uma aplicação (utilizando annotations,
    por exemplo)

    View Slide

  26. somentes os serviços REST podem ser
    descritos pela OpenAPI Specification, isto é,
    nem todos os serviços HTTP podem ser
    descritos

    View Slide

  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

    View Slide

  28. Porque modelar ou
    descrever uma API REST
    utilizando a OAS?

    View Slide

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

    View Slide

  30. são através delas que o front-end de uma
    aplicação se comunica com o back-end…

    View Slide

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

    View Slide

  32. é por esse motivo que modelar e descrever
    uma API é tarefa importante para diversos
    atores como desenvolvedores back-end,
    front-end e testers

    View Slide

  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.

    View Slide

  34. View Slide

  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

    View Slide

  36. para evitar estes tipos de problemas reco-
    menda-se utilizar a abordagem design-first

    para modelar e descrever APIs

    View Slide

  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

    View Slide

  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

    View Slide

  39. e ao descrever a API utilizando a OpenAPI
    Specification tem-se uma linguagem
    comum entre os vários atores envolvidos

    View Slide

  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

    View Slide

  41. além disso pode-se gerar automaticamente,
    por exemplo, uma documentação interativa,
    boilerplate de código e casos de testes

    View Slide

  42. Caso de Uso

    API para gerenciamento

    de palestras

    View Slide

  43. criar uma API REST para o gerenciamento de
    palestras de um evento de tecnologia

    View Slide

  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

    View Slide

  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
    }

    View Slide

  46. é possível filtrar as palestras por nível, data
    de apresentação e se possui live coding

    View Slide

  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
    }
    ]

    View Slide

  48. não é o objetivo da palestra ensinar sobre
    boas práticas ou design de APIs

    View Slide

  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

    View Slide

  50. Modelando uma API REST
    utilizando a OpenAPI
    Specification

    View Slide

  51. um documento OpenAPI pode ser composto
    por um único ou vários arquivos

    View Slide

  52. recomenda-se que o documento raiz tenha
    o nome openapi.yaml ou openapi.json

    View Slide

  53. um documento OpenAPI que descreve uma
    API REST deve ter obrigatoriamente os
    campos openapi, info e paths

    View Slide

  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

    View Slide

  55. exemplo 06
    um documento OpenAPI mínimo

    View Slide

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

    View Slide

  57. exemplo 07
    modelagem inicial do caso de uso

    View Slide

  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: [email protected]
    version: 0.1.0
    paths: {}

    View Slide

  59. pode-se utilizar ferramentas especializadas
    para a descrição e modelagem de APIs
    como o Swagger Editor e o Stoplight

    View Slide

  60. contudo, pode-se utilizar também um editor
    de texto como o VSCode ou uma IDE como o
    IntelliJ ou PhpStorm

    View Slide

  61. exemplo 08
    preview da modelagem inicial do caso de
    uso

    View Slide

  62. View Slide

  63. o campo servers permite descrever um ou
    mais servidores de uma API

    View Slide

  64. exemplo 09

    descrição dos servidores disponíveis no caso
    de uso

    View Slide

  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

    View Slide

  66. View Slide

  67. o campo paths é onde são descritos os
    endpoints e suas operações

    View Slide

  68. um path deve começar com uma barra / e
    pode utilizar placeholders para valores
    como, por exemplo, /talks/{uuid}

    View Slide

  69. ele é concatenado com url do servidor para
    construir a url completa

    View Slide

  70. um path possui campos fixos que
    representam as operações como get, 

    post, put e delete

    View Slide

  71. as operações podem ter os campos
    summary, description, tags, operationId
    que são responsáveis por descrever,
    organizar e identificar as mesmas

    View Slide

  72. exemplo 10

    modelagem dos paths e operações do caso
    de uso

    View Slide

  73. paths:
    /talks/{uuid}:
    put:
    summary: altera os dados de uma palestra
    operationId: updateTalk
    tags:
    - talks
    parameters:
    # !!...
    requestBody:
    # !!...
    responses:
    # !!...

    View Slide

  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

    View Slide

  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

    View Slide

  76. exemplo 11

    modelagem dos parâmetros de uma
    requisição do caso de uso

    View Slide

  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:
    # !!...

    View Slide

  78. o campo requestBody possui os campos
    fixos description, content e required e
    permite descrever o corpo da requisição

    View Slide

  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

    View Slide

  80. exemplo 12

    modelagem do corpo da requisição do caso
    de uso

    View Slide

  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:
    # !!...

    View Slide

  82. o campo responses possui chaves que
    representam os status code possíveis para a
    resposta

    View Slide

  83. e cada status code possui os campos
    description e content e permite
    descrever o corpo da resposta

    View Slide

  84. exemplo 13

    modelagem do corpo da resposta do caso
    de uso

    View Slide

  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'

    View Slide

  86. um schema permite definir tipos de dados e
    podem ser objetos, primitivos ou arrays

    View Slide

  87. ele pode ser utilizado para definir o tipo de
    dados de um parâmetro, corpo de
    requisição ou corpo de resposta

    View Slide

  88. exemplo 14

    utilização de um schema para definir um tipo
    de um parâmetro do caso de uso

    View Slide

  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

    View Slide

  90. pode-se criar schemas mais complexos e
    que podem ser reutilizados em várias partes
    da documentação

    View Slide

  91. exemplo 15

    criação de um schema para ser reutilizado
    do caso de uso

    View Slide

  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

    View Slide

  93. View Slide

  94. Conclusão

    View Slide

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

    View Slide

  96. …para que todos os atores envolvidos façam
    o planejamento antecipado e tenham
    uma compreensão robusta sobre a API

    View Slide

  97. ela permite com que possíveis erros sejam
    antecipados e efeitos indesejados sejam
    evitados como problemas na integração

    View Slide

  98. a OpenAPI Specification funciona como
    linguagem única para a descrição de APIs
    REST e é facilmente legível por humanos e
    máquina

    View Slide

  99. isso faz com que o documento OpenAPI se
    torna a fonte única da verdade sobre a API
    na sua aplicação

    View Slide

  100. além de permitir a geração automática
    de boilerplate de código, documentação
    interativa ou casos de testes

    View Slide

  101. essa apresentação apenas arranhou a
    superfície quando se fala da OAS e suas
    possibilidades

    View Slide

  102. recomenda-se aprofundar os estudos para
    entender melhor os detalhes da OAS como
    media types, recursos de segurança e
    schemas mais complexos

    View Slide

  103. vá em frente e divirta-se!

    View Slide

  104. Referências

    View Slide

  105. bit.ly/palestra-openapi-specification

    View Slide

  106. Avalie!

    View Slide

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

    View Slide