🤶🏽 👨‍💼 📆 Especifique-o. Relatório Yandex ✂️ 🦉 📈

Uma boa especificação de API ajuda os clientes a usá-la. Alguns meses atrás, no Big Pytup, o desenvolvedor do Yandex Alexander Bryazginbryazginnnfez uma apresentação sobre o que a especificação da API REST se baseia como um exemplo do OpenAPI + Swagger e por que esse pacote é necessário. A partir da sinopse, você pode descobrir como estragamos a geração automática da especificação no serviço pronto, quais bibliotecas foram úteis para nós e que tipo de ajuste existe em torno da especificação OpenAPI.

- Olá pessoal, meu nome é Alexander. Eu gostaria de falar com você sobre as especificações.

Gostaria especificamente de abordar vários tópicos. Primeiro de tudo, o que são especificações usando o exemplo de especificações da API REST. Além disso - conforme fixamos a geração da especificação em nosso serviço. E no final, do lado bom - que ferramentas, ajustes, usar os resultados de nossa geração de especificações, usando um exemplo de uma especificação como OpenAPI e Swagger UI.

Especificação da API REST

O que são especificações e o que quero dizer com isso no meu relatório?

Primeiro, é a Interface Description Language, uma linguagem para descrever interfaces, alguma descrição que corresponde a um formato específico. Ele pode ser analisado automaticamente, porque possui um formato estrito e detalhes específicos que não dependem do idioma em que a interface é implementada. Ou seja, digamos que você tenha um servidor web Python, para a Interface Description Language não importa.

Existem muitos idiomas para especificar especificações. Estas são especificações para REST, RPC, GraphQL, etc. Hoje, vamos nos concentrar na especificação REST.

Openapi

Vamos falar sobre especificações usando o exemplo OpenAPI.

Primeiro, vamos entender o que é OpenAPI. Este é apenas o mesmo idioma para descrever as especificações. Por si só, é um arquivo - no formato YAML, JSON ou XML, quem mais gosta - com uma descrição da interface, manipula pontos de extremidade e esquemas.

Swagger

Quando falamos sobre o OpenAPI, não podemos dizer sobre o Swagger.

O Swagger é essencialmente uma interface de usuário OpenAPI que permite visualizar lindamente sua especificação.

No Swagger, como no OpenAPI, há uma descrição dos terminais que estão em sua especificação.

Há uma descrição da autorização na sua API.

Há uma descrição dos modelos ou circuitos com os quais você manipula em sua API - por exemplo, aceite-o para entrada ou retorne-o para saída.

Há uma descrição de exemplos e solicitações e respostas esperadas da sua API.

Além disso, no Swagger, devido ao fato de ser uma interface do usuário e estar em execução no navegador, é possível executar em tempo real solicitações à sua API aqui e agora.

^{_{Link do slide}}

Com tudo isso, você pode brincar em um banco de testes preparado pela equipe Swagger. Este é petstore.swagger.io. Há uma especificação de exemplo, levantada por Swagger. Você pode acessar o back-end real e tocar. Recomendar.

Então, dizemos: OpenAPI, Swagger, especificação. Mas por que tudo isso é necessário para uma pessoa que escreve, digamos, um back-end?

Primeiro, as especificações são frequentemente usadas durante a fase de design da nossa API. Ou seja, as pessoas normais, tendo assumido a tarefa de escrever um back-end, começam descrevendo o que desejam implementar. Ou seja, eles começam a projetar sua API, uma lista de pontos de extremidade que desejam implementar, uma lista de esquemas a serem manipulados, parâmetros etc. Nesse caso, as especificações e ferramentas em torno das especificações são muito convenientes.

Além disso, há um caso popular. Pelo bem do que arrastamos a especificação para nós em serviço? Esta é a documentação. A disponibilidade das especificações oferece uma boa oportunidade para descrever sua API e compartilhar essas informações com alguém: com os provedores front-end da sua equipe ou com clientes externos que desejam se integrar a você.

Além disso, devido ao fato de a especificação ser escrita em um determinado formato estrito, ela pode ser processada automaticamente, ou seja, envolvida na introspecção da API. Além disso, você pode pegar muitas ferramentas que podem facilitar sua vida. Darei a você mais especificamente e com mais detalhes posteriormente.

Como preparamos o OpenAPI

Decidimos por que precisávamos de tudo isso. Vamos falar sobre como estragamos a geração de especificações em nosso serviço. Primeiro, um pouco de contexto.

Quando chegamos à conclusão de que cortaríamos a especificação, não seguimos o caminho normal quando escrevemos o projeto, no sentido de um protótipo com uma especificação. Já levantamos algum back-end, ele já estava voando conosco e queríamos compartilhar a especificação como uma maneira de documentar.

E nosso back-end foi repentinamente em Python. Utilizamos o Falcon como estrutura, o marshmallow como ferramenta de serialização e desserialização e o webargs como ferramenta de validação.

Usando o recorte mais simples da petstore que mencionei anteriormente, vamos imaginar como nosso serviço pode parecer no estágio em que queremos gerar uma especificação.

Em nosso serviço, haveria um par simplificado de esquemas: o tipo de nosso animal de estimação, ou seja, a categoria e, de fato, os próprios animais.

Ou seja, descreveríamos vários esquemas no Marshmallow. Além disso, prepararíamos algumas canetas para, por exemplo, registrar e receber nossos favoritos.

E, de fato, eles descreveriam o próprio aplicativo, o que aumentaria o ponto de extremidade para criar e receber animais de estimação.

É assim que ficaria juntos. Serviço bastante simples.

Vamos pensar em quais opções temos para criar uma configuração OpenAPI. A opção mais simples e ingênua, como eu disse anteriormente, é apenas um arquivo. Por que não fazemos esse arquivo com as mãos? Sabemos quais dados de entrada temos, temos pontos finais. Parece óbvio, basta pegar e escrever.

Mas antes de tudo, somos programadores. Não gostamos de fazer nada com as mãos. Queremos que algo padrão seja gerado para nós. Em segundo lugar, se suportássemos tudo manualmente, certamente teríamos que suportar alterações na API, bem como um arquivo que esteja em outro lugar. Como qualquer serviço, nosso produto é volátil, assim como a especificação.

Portanto, chegamos à conclusão de que queremos gerar uma configuração do OpenAPI. Dada a nossa pilha de tecnologias, encontramos uma biblioteca como apispec . Apispec é uma biblioteca de fabricantes, ou seja, os autores de Marshmallow e Webargs. Juntos, eles formam um grande ecossistema.

Vamos ver como você pode usar o apispec em nossa pilha para ensiná-lo a gerar uma especificação para nós.

Tínhamos um recurso e um manipulador específico para o método get desse recurso. Ele tem algum tipo de corpo.

Para ensinar apispec, para que ele saiba o que estamos fazendo em nossa caneta, adicionamos algo à doutrina. Nós adicionamos uma descrição que é compreensível para o homem. No nosso caso, este é um exemplo de respostas: às vezes isso acontece, nossa caneta responde com duzentos e, no corpo de nossa resposta, há JSON com um esquema, modelo de dados Pet.

Usando o exemplo de uma pós-solicitação, descrevemos: além do fato de haver uma resposta 201 na qual retornamos o Pet, também existe o corpo esperado da solicitação que chega até nós. E dentro dessa solicitação, esperamos JSON e esperamos que esse JSON esteja no formato Pet.

Nós adicionamos documentos, então precisamos aprender como gerar uma especificação. Para fazer isso, escrevemos algum tipo de script, um botão vermelho, e ensinamos o apispec a gerar uma especificação para nós. Declaramos um objeto apispec, do qual descrevemos alguns metadados do nosso serviço e, em seguida, apenas escrevemos o arquivo, a especificação gerada no formato YAML.

Vamos ver o que foi gerado para esse enorme aplicativo neste arquivo.

Primeiro de tudo, neste arquivo, haverá uma descrição da versão na qual a especificação foi gerada. Isso é importante para que todos que interpretam essa especificação entendam qual formato interpretar. As especificações variam de versão para versão.

Além disso, há uma descrição do nosso serviço. Este título, versão, talvez haja alguma descrição, se você quiser, e uma lista de servidores para os quais você pode ir, puxe as canetas, veja e toque em nosso back-end.

Além disso, os próprios esquemas de dados que manipulamos brotam lá, com uma descrição dos tipos, com exemplos de preenchimento desses dados e algumas regras. Talvez esses sejam alguns valores extremos, talvez os parâmetros de ligação. Aqui você vê uma lista dos atributos necessários.

Além dos esquemas, a própria descrição dos pontos de extremidade cresce lá. Nesse caso, a descrição de cada método é gerada.

Usando o método get, obtemos uma descrição do que fazemos com o método get.

E exatamente a descrição que colocamos nas doutrinas do nó de extremidade correspondente surgiu na postagem. Ou seja, já recebemos algum tipo de arquivo.

O que devemos fazer com isso agora? Para que serve? Antes de tudo, você, como proprietário do back-end, já pode dar a todos esses clientes em potencial que irão para suas canetas, fornecer essa especificação. E isso ajudará os caras a se integrarem. Ou seja, o arquivo que geramos não faz você arrancar os olhos. É bastante legível. Pode ser visto através dos olhos e de alguma forma analisado.

Mas isso também é difícil. Vamos ver quais outras ferramentas existem para simplificar sua vida e que tipo de ajuste existe em torno da especificação gerada.

Pãezinhos

E então chegamos ao próximo estágio, onde falaremos sobre o que é um kit de ferramentas útil sobre especificações usando o exemplo OpenAPI.

^{_{Link do slide}}

A primeira ferramenta que eu gostaria de falar é a Swagger-UI. A seguir, fornecerei links para um recurso da Web onde você pode cutucar a ferramenta correspondente, neste caso o SwaggerHub, ou para o comando para iniciar o documento correspondente usando o Docker.

Todos nós amamos muito o Docker. O Docker ajuda você a não colocar JavaScript ou Java no local. Apenas pegue, execute-o com um comando e tudo funcionará para você.

Portanto, o Swagger-UI é, de fato, um utilitário que permite exibir lindamente suas especificações. Como eu disse anteriormente, eles estão sendo executados localmente usando o Docker, possivelmente o Swagger.

Você pode visualizar ou compartilhar no código do idioma executando a especificação no Swagger no seu hardware. Além disso, envie todos os seus usuários em potencial a essa especificação. Ela já é muito mais compreensível, bonita. Diretamente nele, você pode executar a consulta.

^{_{Link do slide}}

Além da interface do usuário do Swagger, há uma ferramenta conveniente do editor do Swagger. Você pode usá-lo na Web, pode buscá-lo em um local ou em qualquer máquina de escrever. Ele permite que você altere as especificações em tempo real e veja sua exibição aqui. Ou seja, é uma ferramenta muito conveniente no estágio de, por exemplo, projetar uma API, quando você não possui uma especificação gerada e deseja, de alguma forma, brincar ou descrever seu back-end sem ter um back-end real ou gerado.

A seguir, a maravilhosa ferramenta Prism. Eu gostaria de me debruçar sobre isso com mais detalhes. Prism é um utilitário do Spotlight. Permite que você, com a especificação, crie o servidor de simulação, que funcionará de acordo com a especificação que você o alimentou.

Ou seja, nesse caso, vemos o lançamento do Prism no topo da especificação, que eu roubei logo abaixo da loja Swagger. Vemos que o Prism encontrou todos os pontos de extremidade especificados na especificação e disse que eles os incomodam honestamente.

Vamos tentar sentir o que o Prism pode fazer.

Primeiro, encontramos a caneta, tentamos puxá-la e de repente vemos que Prism nos diz: desculpe, erro 401. Entramos na especificação e vemos que, de fato, esta caneta está oculta por trás da autorização. A seção de segurança está claramente descrita lá. Nele, vemos que o método de autorização é OAuth e entendemos: na verdade, o Prism esperava algum tipo de dados de autorização de nós.

Vamos tentar transferir dados de autorização para ele de acordo com o formato que ele está esperando. É claro que o token é de alguma forma arejado, pois o Prism não importa o que é em essência. O formato é importante para ele. Ou seja, se ele estiver aguardando o OAuth, ele estará aguardando dados de autorização em um formato específico.

Empurramos com autorização e já vemos o 400º erro. Analisamos o que temos na especificação. Na especificação, vemos que não passamos alguns atributos necessários. Vamos transmiti-los.

O atributo mágico é status. É, de fato, dado de acordo com a especificação ENUM. Se transferíssemos um status que não está incluído neste ENUM, teríamos quatro pontos.

Aqui passamos o status válido e vemos que o back-end respondeu com um xml completamente válido com os dados. Os dados neste xml agora são retornados apenas do exemplo especificado na especificação. Ou seja, na especificação de cada campo, há uma seção como exemplo, onde você pode especificar um exemplo de dados que podem ser retornados. Aqui Prism apenas os trouxe de volta.

Mas, além do fato de que você pode puxar a caneta e esperar que haja uns duzentos honestos, há uma oportunidade de dizer Prism - devolva-me um código de resposta específico. Geralmente, na especificação, descrevemos o comportamento diferente de nossa caneta e, com dados válidos, eles nem sempre correspondem a duzentos. Eles podem procurar, por exemplo, a presença de IDs no banco de dados, para ver se esse ID não existe.

Nesse caso, declaramos um determinado código, digamos, o 400º ou o 422º, para quem você quiser. Ou seja, com uma entrada válida, nem sempre há uma saída válida. Portanto, na especificação, descrevemos várias opções de resposta. E podemos dizer claramente ao puxar a caneta Prism: desta vez, estou esperando que você me responda, digamos, o erro 404. Digamos que esse seja um caso quando eu puxo a alça com um ID, mas não existe esse ID.

Para resumir, quais são os recursos em geral, além dos que eu já mencionei? Novamente, este é um servidor simulado que você pode adquirir. Ele responderá de acordo com a especificação, validará os pedidos de autorização. Ele também será validado nos dados que você enviou para ele.

Além de validar a solicitação, ele irá gerar respostas. No caso mais simples, como eu disse, gera respostas por exemplo. Existe uma segunda opção - quando você solicita explicitamente: gere respostas dinâmicas. Uma estratégia dinâmica significa que, dependendo do tipo, digamos, int, ele irá gerar milhares, bilhões ou algo mais. Ou, para a string, um hash estranho e incompreensível.

Além disso, quando eu disse na primeira execução que você pode gerar dados, nos perguntamos: seria legal se o Prism se integrasse com o faker. Aqueles que usaram o Python provavelmente sabem como é legal quando você deseja bloquear ou emular dados no banco de dados.

Portanto, o Prism é escrito em JavaScript. O JavaScript também possui o Faker.js e o Prism tem integração automática com o faker. Você pode especificar explicitamente em sua especificação os tipos de dados falsos que sua caneta fornecerá. Ou seja, o OpenAPI suporta um sistema de plug-in que permite expandir sua especificação para que o OpenAPI e o próprio analisador não se importem. Mas se houver plugins que analisam sua especificação, eles podem usar alguns campos adicionais.

Portanto, o Prism oferece a você o uso do campo opcional do plugin X-faker. Muito confortavelmente.

Aqui, sob o asterisco, indiquei que os retornos de chamada podem ser descritos no OpenAPI. Esse é o esquema de interação quando você registra um retorno de chamada para uma determinada caneta e espera que, depois disso, você receberá um retorno de chamada específico para o URL que registrou. Então, Prism e ele sabe como se molhar.

De interessante: o Prism pode ser aumentado não apenas no modo de simulação, mas também no modo de proxy. Você apenas coloca esse Proxy na frente do seu back-end real e, todas as solicitações que passam pelo Prism e retornam, o Prism valida conforme as especificações.

Se alguns dados - digamos, entrada ou saída, solicitação ou resposta - divergirem, ele escreverá isso no log. Ele faz isso de forma bastante transparente, não afeta o comportamento real. Em geral, a documentação diz que pode ser facilmente aumentada na produção. Honestamente, eu não tentei isso sozinho. Certamente há algum tipo de sobrecarga, mas ainda não posso dizer sobre isso. Você pode sentir, tentar contar.

Além disso, através do que eu já disse, é possível forçar certos pedidos. Ou seja, acesse o servidor de simulação e diga: Quero um exemplo ou tipo de resposta específico. Já falamos sobre o tipo de resposta. Também na especificação OpenAPI é possível especificar várias opções de resposta e nomeá-las explicitamente.

Então, você pode vir e dizer Prism: desta vez eu quero um exemplo específico, da próxima vez eu quero outro exemplo.

^{_{Link do slide}}

Sobre o Prism falou. Agora sobre o Postman. Eu o amo tanto. Portanto, o Postman tem uma integração imediata com o OpenAPI. Você pode literalmente importar a especificação OpenAPI com apenas dois cliques nos botões. E ele criará uma coleção de solicitações de acordo com sua especificação.

Ao mesmo tempo, ele preparará todos os parâmetros de consulta, todos os parâmetros do corpo, todo o ambiente e autorização. Você só precisa finalizar os dados com alguns IDs reais ou qualquer outra coisa, tokens de autorização. Muito confortavelmente.

Passamos mais do Postman. Nós conversamos sobre o Prism, ele tem funcionalidade - validação de consulta. De fato, existe um utilitário separado que permite que você sugue sem piedade seu back-end em execução e verifique se ele realmente funciona de acordo com a especificação.

Dredd analisa a especificação. Ele pega, puxa todas as canetas e olha o que voltou para ele. Em geral, o dredd pode ser tratado como uma infraestrutura para escrever testes, porque todos os seus pedidos podem ser complementados com seus ganchos. Ou seja, da caixa, você pode começar a usar o dredd exatamente como está, como eu o lancei aqui.

Ou você pode executar o dredd passando um conjunto de ganchos que realmente funcionam na ideologia de um teste regular. Há algo que se eleva a todo o conjunto de testes, há ganchos que são executados antes do teste, após o teste, toda a infraestrutura.

^{_{Link do slide}}

Em seguida, quero falar mais detalhadamente sobre essa ferramenta do Swagger como Swagger-codegen. De fato, é um pouco como uma faca suíça. Para começar, que tipo de pensamento os caras tiveram quando escreveram este instrumento.

Geralmente, quando alguém precisa se integrar a um back-end, você raramente descreve uma solicitação http aqui, em um determinado estágio, na lógica de negócios. Na maioria das vezes, você encapsula o trabalho com um back-end específico em alguma entidade, no cliente.

Então, os caras tiveram a ideia de que, com uma especificação, podemos descrever e prever com clareza como seria o cliente para esse back-end. E os caras fizeram um gerador de clientes.

Vamos tentar iniciar a geração do cliente de acordo com a especificação petstore. Veremos que esse gerador foi gerado pelo próprio cliente Swagger, no qual existe o próprio cliente Python. Aqui na linha de lançamento, você pode ver claramente que estou gerando um cliente em Python. De fato, ele suporta um grande número de idiomas. O que é importante aqui? Os pioneiros vão gostar do JavaScript, os descolados vão gostar do Go. Tudo o que você quiser.

Portanto, além do cliente em Python, ele gerou alguns documentos e testou pastas mágicas. Falaremos sobre eles mais tarde em mais detalhes. E muito açúcar para que você possa agrupar esse cliente em uma biblioteca pronta. Há gitignore, existem arquivos de CI, digamos que para Travis, há açúcar para git. Existem requisitos, setup.py e tox.ini. Ou seja, tudo o que ajuda você a simplesmente pegar, confirmar e enviar esse cliente já está na forma de uma biblioteca que pode ser reutilizada.

Vamos dar uma olhada no que ele gerou no cliente.

No cliente, ele gerou, além de alguns arquivos auxiliares, dois diretórios api e modelos muito importantes. Nos modelos, temos esses modelos de dados que manipulamos. Cada modelo é simplesmente uma classe Python, herdada do objeto com __init__, que aceita todos os tipos de parâmetros para esse esquema e getters e setters que alteram o estado do objeto.

Além do modelo, entidades como PetApi também apareceram lá - são apenas wrappers de clientes sobre o grupo de terminais, que o OpenAPI agrupa por tags ou por terminais.

E esse cliente possui todas as canetas que você pode mexer, transmitindo dados reais. Então eles voarão para algum back-end.

O que é implementado a partir deste cliente gerado? Do interessante - a abordagem contratual. Vamos falar mais sobre ele.

A abordagem contratual da programação sugere que, ao implementar a interação entre o cliente e o servidor, você sempre estabelece determinadas regras, contratos, sejam dados que o cliente fornece ao servidor ou dados que o servidor fornece ao cliente.

Portanto, a abordagem do contrato recomenda que você verifique seus dados e sua interação quanto à conformidade com o contrato sempre em tempo real. Se este contrato é um esquema dos dados que transmitimos e não atende às nossas expectativas, não é satisfeito, é preciso dizer isso, mostrar o erro aqui e agora. Não vá para o back-end real, não espere por quatro pontos, mas diga agora.

Ou outro caso: fomos ao back-end, recebemos alguns dados, mas eles não correspondem ao que estávamos esperando. Suponha que alguns campos que esperamos ver preenchidos fiquem vazios. Falaremos sobre isso aqui e agora, e não quando deixarmos algum lugar na pilha de chamadas em algum lugar da floresta e não descobrirmos por que algo caiu.

Portanto, o Swagger-codegen gera clientes e modelos de acordo com a abordagem do contrato. Ele permite que você diga em tempo real: sim, quero que o cliente em tempo de execução verifique todos os dados quanto à conformidade com os contratos. E se o contrato não for cumprido, ele dirá imediatamente.

Geramos algum tipo de cliente pit com uma abordagem contratual, mas, além disso, o Swagger-codegen gerou stubs de documentação para nós. Na verdade, eles são bastante simples, mas todos podem ser distorcidos para cada modelo.

O Swagger-codegen também gerou algum tipo de esboço de teste. Tudo para que você possa acumular o código gerado com o mínimo de esforço e executá-lo com testes, com Integração Contínua, na forma de uma biblioteca com um git, com todos os sinos e assobios.

Vamos passar por isso brevemente novamente. Analisamos apenas um caso - uma maneira de gerar clientes para a API. Da importante abordagem contratual. Eu gostaria de dizer: quando eu criei um cliente para uma petstore real de acordo com as especificações e realmente fui para o back-end, subitamente essa abordagem contratual capturou os dados inválidos retornados pela petstore.

No começo eu pensei - eles são um pouco estranhos. Eles mesmos geraram a especificação e o back-end não funciona corretamente para eles. Mas parece-me que eles fizeram isso de propósito, para que pudéssemos ver o poder do contrato se aproximando. Não havia muitos dados e eles foram gerados claramente.

Também na geração de clientes e em outra geração, você pode usar seus próprios modelos. Ou seja, se você deseja gerar um cliente em um determinado formato, pode salvar e preparar seu modelo e gerar clientes da maneira que desejar. Se você sair por aí e gerar integrações todos os dias, poderá gostar muito.

Você também pode configurar esses clientes e gravar a importação de seus modelos, em vez daqueles gerados pelo Swagger-codegen.

Além de gerar clientes para a API, você pode alimentar a especificação para o gerador e gerar os stubs do próprio servidor. É muito estranho. Ou seja, você gera algum tipo de back-end que supostamente funciona de acordo com a especificação. É claro que não há lógica de negócios lá. Mas talvez seja conveniente como algum tipo de andaime, ou seja, preparar um rascunho com o qual você já possa fazer alguma coisa. Eu não o usei, mas recomendo dar uma olhada - talvez você encontre algo útil para si mesmo.

Entre outras coisas, ele permite gerar documentação nos formatos HTML e Confluence, se alguém estiver usando. Os exemplos que eu queria mostrar para o OpenAPI também terminaram aí.

^{_{Todas essas ferramentas estão disponíveis nos dois links abaixo no slide: openapi.tools egithub.com/APIs-guru/awesome-openapi3}}

Quero mostrar os grupos de ajuste em torno da especificação OpenAPI. De fato, existem muitas ferramentas. Estes são apenas grupos, ou seja, tipos de ferramentas que você pode usar.

O importante aqui é um conversor de uma especificação para outra. Ou seja, você pode gerar a API do Blueprint ou o que quiser da especificação OpenAPI e vice-versa. Existe uma biblioteca para simulação, para documentação. Ou seja, tudo sobre o que eu falei será refletido nesses grupos.

Há um link que você pode seguir também. Certifique-se de ir olhar.

^{_{Link do slide}}

Além das ferramentas em torno do OpenAPI, existem ferramentas em torno do Swagger. Existem o SwaggerHub e o Swagger Inspector. Eles são destacados em azul porque é um kit de ferramentas baseado na Web. Você pode ir diretamente para lá e, como serviço, usar o SwaggerHub e o Swagger Inspector, que são na verdade uma superposição das seguintes bibliotecas: Swagger-editor, Swagger-codegen, Swagger-UI. Tudo o que acabamos de discutir.

Todas as bibliotecas são amarelas, são de código aberto, como vimos. Existe no GitHub, está na forma de Docker. Usar.

Conclusão

O que discutimos hoje? Especificação da API REST usando OpenAPI e Swagger como exemplos. Quero enfatizar que o OpenAPI é apenas uma maneira de descrever a especificação. Muitos deles. Dos mais interessantes, veja também a API do Blueprint. Talvez alguém mais goste de alguma coisa.

Também assistimos o Swagger. Em essência, isso, como já dissemos, é apenas uma bela interface de usuário em torno da especificação, que permite que você a observe e explore de uma maneira conveniente. De fato, essas ferramentas também são muitas, desde o popular ReDoc e Sphinx até o Markdown. Ou seja, você pode gerar o Markdown a partir do OpenAPI, e ele será exibido maravilhosamente em todo o GitHub, GitLab - onde você quiser.

Também vimos um exemplo em nossa pilha de tecnologias de como agora geramos a especificação. Mas, como você notou, isso é bastante complicado e inconveniente, porque, de fato, duplicamos a lógica e as doutrinas de negócios.

^{_{Links do slide: FastAPI , SAFRS , rororo}}

De interessante, recomendo que você consulte o FastAPI. Styopa vai lhe contar mais sobre isso hoje . O FastAPI ajuda a gerar uma especificação pronta para uso. Você não pode pensar em nada. Basta escrever o código e obter a especificação final.

Existem mais duas estruturas: SAFRS e rororo. Os nomes, é claro, são mágicos. Eles trabalham um pouco em um modelo diferente, não fazem você não pensar na especificação e a obtém apenas como um efeito colateral. Pelo contrário, você tem uma especificação que conduz manipuladores. Este é, grosso modo, desenvolvimento orientado por especificação. Eles não têm tantas estrelas quanto o FastAPI, mas parece-me que eles merecem atenção, dê uma olhada.

E, finalmente, discutimos que tipo de utilidade existe em torno da especificação usando os exemplos de OpenAPI e Swagger. Para todos os pontos em que faço links, tenha certeza, há muitas coisas interessantes:

- OpenAPI / Swagger
swagger.io/docs/specification/about

- Exemplo em falcon + marshmallow + apispec
github.com/marshmallow-code/apispec
github.com/tiangolo/fastapi

- AbraAPI / Swagger
pães
openapi.tools swagger.io/tools swagger.io/tools/open-source/open-source-integrations github.com/APIs-guru/awesome-openapi3

O que eu tenho foi a mensagem do relatório? Pessoal, escrever especificações não é algum tipo de burocracia. E isso não é tão difícil quanto pode parecer à primeira vista, mas sim simples e fornece muitas ferramentas úteis, abre grandes oportunidades para você.

Escreva as especificações. Recomendar. Muito obrigado.

Todo o código e links estão disponíveis na apresentação .