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 full-size slide

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

    View full-size slide

  3. @phpsp
    phpsp.org.br

    View full-size 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 full-size 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 full-size slide

  6. A onipresença das APIs
    no mundo moderno

    View full-size 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 full-size 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 full-size 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 full-size 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 full-size 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 full-size slide

  12. O que é uma
    API REST?

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  19. O que é a OpenAPI
    Specification?

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size 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 full-size 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 full-size slide

  34. 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 full-size slide

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

    para modelar e descrever APIs

    View full-size slide

  36. 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 full-size slide

  37. 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 full-size slide

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

    View full-size slide

  39. 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 full-size slide

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

    View full-size slide

  41. Caso de Uso

    API para gerenciamento

    de palestras

    View full-size slide

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

    View full-size slide

  43. 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 full-size slide

  44. !// 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 full-size slide

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

    View full-size slide

  46. !// 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 full-size slide

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

    View full-size slide

  48. 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 full-size slide

  49. Modelando uma API REST
    utilizando a OpenAPI
    Specification

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  53. 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 full-size slide

  54. exemplo 06
    um documento OpenAPI mínimo

    View full-size slide

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

    View full-size slide

  56. exemplo 07
    modelagem inicial do caso de uso

    View full-size slide

  57. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  62. exemplo 09

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

    View full-size slide

  63. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    post, put e delete

    View full-size slide

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

    View full-size slide

  69. exemplo 10

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

    View full-size slide

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

    View full-size slide

  71. 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 full-size slide

  72. 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 full-size slide

  73. exemplo 11

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

    View full-size slide

  74. 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 full-size slide

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

    View full-size slide

  76. 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 full-size slide

  77. exemplo 12

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

    View full-size slide

  78. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

  81. exemplo 13

    modelagem do corpo da resposta do caso
    de uso

    View full-size slide

  82. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

  85. exemplo 14

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

    View full-size slide

  86. 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 full-size slide

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

    View full-size slide

  88. exemplo 15

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

    View full-size slide

  89. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  98. vá em frente e divirta-se!

    View full-size slide

  99. Referências

    View full-size slide

  100. bit.ly/palestra-openapi-specification

    View full-size slide

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

    View full-size slide