OpenAPI and Swagger Ecosystem

Olá, daqui fala o Alex da DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 1 de 19. As APIs impulsionam a web moderna, mas como é que comunicam entre si sem tentativa e erro interminável? Precisas de uma forma fiável de saber exatamente o que um servidor espera e o que vai devolver, antes de escreveres uma única linha de código. Esse mecanismo é o contrato de API, regido pela OpenAPI Specification. A OpenAPI Specification é uma interface standardizada e agnóstica da linguagem para REST APIs. Pensa nela como uma planta de arquitetura. Quando bem definida, tanto um humano como uma máquina podem olhar para esta planta e perceber exatamente o que um serviço faz. Não precisam de aceder ao source code, não precisam de ler documentação separada em PDF, e não precisam de inspecionar o tráfego de rede em tempo real. A especificação descreve claramente os endpoints disponíveis, os inputs precisos que requerem e as estruturas exatas dos dados que devolvem. É escrita em plain text, usando YAML ou JSON, o que a torna universalmente legível tanto por ferramentas automatizadas como por developers humanos. Se trabalhas com APIs, provavelmente já ouviste falar do termo Swagger. As pessoas usam muitas vezes Swagger e OpenAPI de forma intercambiável, mas hoje em dia representam conceitos completamente diferentes. Originalmente, a própria especificação chamava-se Swagger. Em 2015, os criadores doaram a especificação à Linux Foundation, onde foi oficialmente rebatizada de OpenAPI Specification. Hoje, OpenAPI refere-se estritamente às regras e ao standard. Swagger refere-se ao ecossistema de ferramentas comerciais e open-source criadas pela SmartBear que implementam essas regras. Por exemplo, o Swagger UI gera documentação interativa, e o Swagger Editor ajuda-te a escrever os ficheiros. Escreves um documento OpenAPI, mas podes usar as ferramentas Swagger para o visualizar. Isto leva-nos ao verdadeiro poder da especificação, que é o design-first development. Sem um contrato claro, o desenvolvimento de APIs geralmente acontece de forma linear. A equipa de backend escreve o código, expõe um novo endpoint e, em seguida, entrega alguma documentação escrita. Entretanto, a equipa de frontend fica parada, à espera que o backend termine para poderem começar a integrar a user interface. Aqui está o ponto-chave. Quando adotas o OpenAPI, invertes esse processo. Antes de alguém escrever o código da aplicação, ambas as equipas chegam a acordo sobre o documento OpenAPI. Este ficheiro de texto torna-se um contrato rigoroso que elimina todas as suposições. A equipa de backend utiliza-o para gerar server stubs e validar se a sua implementação cumpre os requisitos acordados. Simultaneamente, a equipa de frontend usa exatamente o mesmo documento para gerar mock servers. Podem começar imediatamente a construir a user interface, fazendo network requests para um backend simulado que se comporta exatamente como a API final se vai comportar. Nenhuma equipa bloqueia a outra. Como este contrato é machine-readable, também resolve permanentemente o problema da documentação desatualizada. Quando um requisito da API muda, atualizas primeiro o ficheiro de especificação. O teu tooling regenera depois automaticamente a documentação web, os mock servers e as client libraries. A documentação e o código permanecem perfeitamente sincronizados porque partilham uma single source of truth. Uma especificação de API não é apenas um mecanismo para gerar páginas web bonitas; é um protocolo de comunicação fundamental para as tuas equipas de engenharia, que transforma suposições humanas em regras executáveis. Se gostas do programa e queres apoiar-nos, procura por DevStoriesEU no Patreon. Obrigado por ouvires. Até à próxima!

Olá, daqui é o Alex do DEV STORIES DOT EU. OpenAPI e o Ecossistema Swagger, episódio 2 de 19. Escrever documentação é aborrecido, mas e se o teu código escrevesse a documentação, e a tua documentação escrevesse o código? Este workflow bidirecional é a principal promessa do ecossistema Swagger open-source. Um equívoco comum é achares que tens de adotar todo o ecossistema em simultâneo. Não tens. O conjunto de ferramentas é totalmente modular. Podes escolher componentes individuais com base nas tuas necessidades específicas de workflow, quer estejas apenas a renderizar documentação existente ou a fazer o scaffolding de um backend completamente novo. As principais ferramentas open-source funcionam como um pipeline. Desenhas a API no Swagger Editor, visualizas no Swagger UI e automatizas as implementações usando o Swagger Codegen. O Swagger Editor é onde o design da API começa. É um ambiente baseado no browser onde escreves a tua especificação OpenAPI em YAML ou JSON. À medida que escreves, o editor valida continuamente a tua sintaxe contra as regras da especificação OpenAPI. Se colocares um campo no sítio errado ou definires um data type inválido, o editor assinala o erro imediatamente. Oferece uma vista de ecrã dividido em tempo real, mostrando o texto raw de um lado e uma preview visual do outro. Assim que o contrato for válido, podes passar para a automação com o Swagger Codegen. Esta ferramenta pega no teu ficheiro de especificação OpenAPI e traduz para source code funcional. Suporta dezenas de linguagens e frameworks. Podes gerar server stubs, que fornecem o boilerplate de routing e controllers para o teu backend. Em alternativa, podes gerar client SDKs, que as aplicações consumidoras usam para interagir com a tua API sem terem de escrever lógica de requests HTTP customizada. Depois, temos o Swagger UI. Esta ferramenta faz o parse da tua especificação e renderiza-a como uma página de documentação interativa baseada na web. Vai além do texto estático. O Swagger UI gera campos de input e botões de execução diretamente a partir das tuas definições de API. Os utilizadores podem inserir parâmetros, anexar tokens de autenticação, enviar requests HTTP reais para os endpoints da tua API e inspecionar as responses diretamente no browser. Considera um workflow concreto que combine estas três ferramentas. Começas no Swagger Editor, a desenhar a especificação para uma nova API de gestão de utilizadores. Defines os endpoints, os payloads dos requests e as responses esperadas. Assim que o contrato estiver completo, passas esse ficheiro para o Swagger Codegen, configurando-o para fazer o output de um server stub em Node.js. O Codegen gera automaticamente a estrutura de diretórios, a configuração de packages e os route handlers. Só precisas de escrever a business logic específica e as queries à base de dados dentro desses controllers pré-configurados. Entretanto, entregas esse exato mesmo ficheiro de especificação OpenAPI à tua equipa de QA, servido através do Swagger UI. Os engenheiros de QA não precisam de ler o teu ficheiro YAML nem de olhar para o teu código Node.js. Eles abrem a página web do Swagger UI, veem os inputs necessários e começam a enviar payloads de teste para o teu novo servidor Node.js imediatamente. Aqui está o ponto-chave. O ecossistema Swagger open-source muda o desenvolvimento de APIs: em vez de escreveres código backend e esperares que a documentação se mantenha precisa, defines primeiro um contrato rigoroso, onde a documentação user-facing e o boilerplate do servidor são gerados exatamente da mesma source of truth. É tudo por este episódio. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui é o Alex da DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 3 de 19. Antes de poderes mapear uma API complexa, precisas de uma tela em branco, mas começar com a estrutura básica errada vai quebrar silenciosamente toda a tua toolchain mais à frente. Isso leva-nos à Anatomia de um Documento OpenAPI. Na sua essência, um documento OpenAPI é definido estritamente como um objeto JSON. Podes escrever o teu ficheiro usando o formato JSON ou o formato YAML. O tooling suporta ambos, e o data model subjacente permanece exatamente o mesmo. Como mapeia diretamente para um objeto JSON standard, as regras de formatação são rígidas. Cada nome de campo é completamente case-sensitive. Se a especificação dita um nome de campo em minúsculas, escrevê-lo com a primeira letra maiúscula significa que o parser o vai ignorar ou lançar um erro. Ao organizares o teu projeto, tens uma escolha na estrutura do documento. Podes definir tudo dentro de um único ficheiro monolítico. Em alternativa, podes dividir as tuas definições por uma estrutura multi-documento. Num setup multi-documento, um ficheiro root atua como entry point e faz a ligação para ficheiros externos usando reference pointers. Quer uses um ficheiro ou cinquenta, o parser acaba por resolvê-los num único objeto JSON lógico em memória. Pega num cenário concreto. Estás a começar um projeto novo. Crias um ficheiro de texto em branco chamado openapi ponto yaml. Antes de tentares desenhar qualquer lógica, queres estabelecer uma baseline validada. Para passar num schema validator, a tua tela em branco tem de conter exatamente dois campos de root-level. O primeiro campo obrigatório chama-se openapi. O seu valor é uma string que especifica a versão exata da OpenAPI Specification que estás a usar, como 3.1.0. É extremamente comum confundir este campo com a versão da tua própria API. Eles não têm qualquer relação. A version string do openapi existe estritamente para compatibilidade de tooling. Quando um code generator ou um documentation viewer abre o teu ficheiro, lê este campo primeiro para determinar que regras de parsing aplicar. Se declarares 3.0.0 aqui, mas usares features da 3.1.0, as tuas validation tools vão falhar porque estão a avaliar o teu documento contra o rule set errado. Aqui está o ponto-chave. O segundo campo root obrigatório é onde entram os detalhes reais da tua API. Este campo é o objeto info. O objeto info fornece a metadata para a tua aplicação. Não vamos detalhar o seu conteúdo interno aqui, a não ser para dizer que requer um title e a sua própria version string. Essa version string interna dentro do objeto info é onde defines se a tua aplicação está na versão um ou na versão dois. Assim que o teu ficheiro openapi ponto yaml contiver apenas estes dois campos root, openapi e info, tens um documento OpenAPI estruturalmente completo. Podes passar este ficheiro por um validator agora mesmo, e ele vai passar sem problemas. Estabelecer esta estrutura mínima válida garante que o teu parser e a tua toolchain estão a funcionar perfeitamente antes de introduzires a complexidade da routing logic real. Obrigado por ouvirem, happy coding a todos!

Olá, daqui é o Alex da DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 4 de 19. Se a tua API for abaixo, como é que um consumer sabe quem contactar? A resposta está logo no topo da tua spec. Estamos a falar sobre preparar o terreno: Info e Servers. Antes sequer de um developer fazer um request ou inspecionar um data model, precisa de contexto. Os objetos Info e Server dão-te exatamente isso. Pensa neles como a capa e a lista de contactos da tua API. O objeto Info é o teu hub de metadata. Há dois fields aqui que são estritamente obrigatórios. O primeiro é o title, que é simplesmente o nome human-readable da tua aplicação. O segundo é a version. O pessoal costuma confundir isto com a version da spec OpenAPI. São coisas completamente distintas. A version do OpenAPI diz ao parser que conjunto de regras de sintaxe deve seguir. A version do Info é o release number da tua própria API, algo como 1.0.5. Diz ao consumer para que iteração do produto está a olhar. Para além dos fields obrigatórios, o objeto Info permite-te adicionar contexto. Podes incluir uma description, que suporta formatação CommonMark. Isto permite-te escrever documentação detalhada e legível, com parágrafos e links diretamente na spec. Podes também definir um objeto contact, que contém um name, um URL e um endereço de email. Se alguma coisa falhar ou um developer precisar de acesso, isto diz-lhes exatamente para onde ir. Por fim, o objeto license permite-te especificar os termos legais sob os quais a API opera, exigindo um name e, opcionalmente, um URL a apontar para o texto da licença. Assim que o objeto Info estabelece o que a API é, o array Servers diz ao consumer onde ela está alojada. Sem isto, os consumers sabem o que a tua API faz, mas não onde a encontrar. Tu forneces um array de objetos Server que representam os diferentes environments onde a tua API está alojada. Cada objeto Server requer um único field, que é o URL. Aqui está o ponto chave. Não estás limitado a um único base URL. Podes definir várias entries de server para refletir a tua infraestrutura real. Por exemplo, o teu primeiro objeto Server pode conter o teu URL de production a usar um endereço HTTPS seguro, com uma description a rotulá-lo explicitamente como o environment de production live. O teu segundo objeto Server pode apontar para um URL de staging ou sandbox, com uma description a notar que é estritamente para testes. Quando estruturas os teus servers desta forma, as tools de documentação interativa e os client generators tornam-se muito mais poderosos. Em vez de forçares um developer a configurar manualmente o base URL para cada request, eles podem simplesmente selecionar staging ou production a partir de um dropdown na sua interface. As tools fazem parse do teu array de servers e encaminham automaticamente os requests para o host correto. Podes também usar URLs relativos se o teu documento OpenAPI estiver alojado diretamente no server que fornece a API. Isto torna mais fácil fazer deploy do exato mesmo ficheiro de spec em diferentes environments, sem estares constantemente a atualizar o endereço do host. Definir objetos Info e Server precisos significa que a tua API não é apenas uma coleção solta de operations, mas um serviço totalmente identificado, legalmente claro e fisicamente localizável. A qualidade de qualquer integração automatizada vai depender inteiramente da precisão destes base URLs. Por este episódio é tudo. Obrigado por ouvires, e continua a programar!

Olá, daqui fala o Alex da DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 5 de 19. Qualquer API REST precisa de endpoints, mas como é que provas matematicamente a uma máquina que métodos HTTP são permitidos e onde? Mapeando-os logicamente. Hoje, vamos olhar para o mapeamento dos Paths e Operations da API. Pensa no Paths Object do OpenAPI como o router central da tua documentação. Funciona como um diretório que mapeia URLs relativos a funcionalidades específicas. Antes de olharmos para o que lá está dentro, temos de esclarecer um mal-entendido comum. Os paths têm de começar sempre com uma barra. São estritamente relativos ao URL do teu servidor, nunca absolutos. Se a tua API estiver alojada em api ponto example ponto com, o teu path é simplesmente barra users, e não o domínio completo. A especificação depende desta formatação exata para anexar corretamente o path ao endereço base do servidor. Dentro do Paths Object, defines rotas individuais usando keys de string. O valor atribuído a cada key de rota chama-se Path Item Object. Um Path Item Object é, fundamentalmente, apenas um contentor. Agrupa todos os métodos HTTP permitidos nesse URL específico. Não dita inputs ou outputs diretamente. Em vez disso, guarda keys que representam métodos HTTP standard, como get, post, put ou delete. Quando mapeias um desses métodos HTTP dentro de um Path Item, o valor que lhe associas é um Operation Object. O Operation Object é onde a ação propriamente dita é definida. Descreve exatamente o que um cliente pode fazer ao enviar esse método específico para esse path exato. Para visualizares a estrutura, considera um endpoint standard de gestão de utilizadores. No teu Paths Object raiz, defines uma key chamada barra users. O valor associado a ela é o teu Path Item Object. Dentro desse contentor, defines uma key get e uma key post. A key get contém um Operation Object que explica como a API devolve uma lista de utilizadores. A key post contém um Operation Object completamente separado, que descreve como criar um novo utilizador. Ambas as operações partilham o URL idêntico barra users, mas a especificação trata-as como ações lógicas distintas, aninhadas debaixo das suas respetivas keys de método HTTP. Dentro de cada Operation Object, vais tipicamente definir dois campos para estabelecer a identidade: o summary e o operationId. O summary é uma string curta destinada a leitores humanos. Para o método get no nosso path barra users, o summary pode simplesmente ser Listar todos os utilizadores registados. Aparece nas interfaces de documentação geradas para que os developers possam examinar rapidamente os endpoints disponíveis. Aqui está o ponto chave. O campo operationId destina-se às máquinas. É uma string única usada para identificar a operação em todo o documento da tua API. Os geradores de código dependem muito do operationId para nomear as funções e os métodos dentro dos SDKs de cliente que constroem. Se deres à tua operação get um operationId de listUsers, o cliente Python ou TypeScript gerado terá uma função chamada especificamente listUsers. Esta string tem de ser absolutamente única. Se duas operações partilharem o mesmo operationId, as ferramentas de geração automatizada vão produzir código com erros ou falhar completamente. A estrutura depende de um aninhamento estrito e previsível. Os paths mapeiam para Path Items, os Path Items mapeiam para métodos HTTP, e os métodos mapeiam para Operation Objects definidos por identificadores únicos. Dominar esta hierarquia exata garante que tanto os developers humanos como as ferramentas de automação downstream possam interagir com a arquitetura da tua API sem terem de adivinhar. É tudo por este episódio. Até à próxima!

Olá, daqui é o Alex do DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 6 de 19. Endpoints estáticos só te levam até certo ponto. Para construíres uma API realmente útil, precisas de uma forma de passar argumentos dinâmicos diretamente no request para alterar como uma operação é executada ou a que dados se destina. Este episódio é todo sobre Endpoints Dinâmicos com Parameters. Vamos começar pelo próprio path do URL. No OpenAPI, defines secções dinâmicas de um URL usando path templating. Fazes isso envolvendo o nome de uma variável entre chavetas. Pensa numa API de e-commerce. Se quiseres ir buscar uma encomenda específica, o teu path será algo como barra orders barra abre chaveta orderId fecha chaveta. Dentro do teu documento OpenAPI, descreves esta variável usando um Parameter Object. Especificas a sua localização definindo o campo in com o valor path. Às vezes, as pessoas tentam tornar os path parameters opcionais. Não podes fazer isso. Um path parameter define estruturalmente a route. Se o parameter estiver ausente, a route simplesmente não existe. Devido a esta regra, qualquer parameter onde a localização seja path tem de definir sempre o campo required como true. E se quiseres modificadores opcionais? Isso leva-nos à segunda localização, onde o campo in é igual a query. Os query parameters aparecem exatamente no final do URL, a seguir a um ponto de interrogação. Voltando à nossa API de e-commerce, podes querer uma lista de encomendas, mas só queres ver as que já estão em trânsito. Acrescentas ponto de interrogação status igual a shipped ao URL. Ao contrário dos path parameters, os query parameters não definem a localização do recurso. Eles filtram ou modificam o resultado, o que significa que o seu campo required pode ser definido como true ou false. O URL não é o único lugar para passar parameters. O Parameter Object suporta mais duas localizações. Definir o campo in como header permite-te definir HTTP headers customizados esperados pela tua operação. Por exemplo, podes exigir um header customizado que indique um tipo específico de dispositivo do client. Nota que headers standard como Accept ou Authorization são estritamente excluídos do Parameter Object porque são tratados noutro lugar no OpenAPI. Por fim, definir a localização como cookie permite-te documentar parameters passados através de cookies do browser, como um session token temporário. Declarar onde um parameter vive é apenas o primeiro passo. Também precisas de definir a sua estrutura. Dentro do Parameter Object, usas o campo schema para definir o data type subjacente. Isto diz ao consumidor da API exatamente se esse orderId é um integer, uma string, ou um formato específico como um UUID. Depois tens o campo style. Isto dita como o parameter é serializado no HTTP request. A serialização importa imenso quando estás a passar dados complexos como arrays ou objects. Se passares uma lista de statuses numa query string, o campo style determina o formato. Um valor de style de form pode separar múltiplos valores com um ampersand, enquanto um valor de style de simple gera uma lista separada por vírgulas. Ao combinar os campos location, schema e style, dás ao client instruções exatas sobre como formatar o network request. Aqui está o ponto chave. O Parameter Object não descreve apenas inputs como uma cortesia. Ele dita estritamente o footprint exato do que uma operação aceita, forçando data types e formatos antes de uma única linha da tua lógica de backend correr. Se estás a achar estes episódios úteis, podes apoiar o programa procurando por DevStoriesEU no Patreon. É tudo por este episódio. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui fala o Alex da DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 7 de 19. Quando envias centenas de campos para uma API, os query parameters falham. Precisas de um pacote estruturado. Esse pacote é definido por estruturar os Input Request Bodies. Enquanto os GET requests dependem do URL path e da query string, os POST, PUT e PATCH requests fazem o trabalho pesado, transportando um payload. Este payload contém dados complexos e nested. Nas especificações Swagger 2.0 mais antigas, talvez te lembres de definir body parameters ou form parameters diretamente junto com os inputs de header e path. O OpenAPI versão 3 mudou isto fundamentalmente. Eliminou completamente os body parameters e introduziu um único Request Body Object dedicado. O Request Body Object reside no nível da operação do teu API design. A sua característica principal é que depende fortemente de content negotiation. Não descreves apenas os dados; mapeias os dados para media types específicos. Este mapeamento ocorre dentro do content map. O content map é um dicionário em que as keys são MIME types padrão, como application slash json, e os values são Media Type Objects que detalham a aparência desse payload específico. Imagina um client a fazer o upload de um novo perfil de utilizador. O perfil contém um nome, um endereço de e-mail, preferências do utilizador e um nested address object. Em vez de enfiar isto tudo em URL variables, o client envia um payload JSON. No teu documento OpenAPI, na secção do request body, crias um content map com a key exata application slash json. Isto declara explicitamente que a API aceita apenas JSON para esta operação. Se um client tentar enviar XML ou plain text, o servidor sabe imediatamente que deve rejeitar o request com um erro de unsupported media type. Esta estrutura é altamente flexível. Se o upload do teu perfil de utilizador exigir uma foto de perfil junto com os dados textuais, tratas disso exatamente no mesmo lugar. Adicionas uma segunda key ao content map para multipart slash form-data. Este Media Type Object especifica então as regras para o payload misto. Cada media type recebe a sua própria definição independente. Isto permite que o exato mesmo endpoint da API processe formatos de dados fundamentalmente diferentes, com base exclusivamente no header Content-Type que o client envia no HTTP request. Dentro do próprio Request Body Object, junto com o content map, vais encontrar uma flag required. Trata-se de uma propriedade boolean simples. Defini-la como true significa que o request vai falhar imediatamente se o client enviar um body vazio. Isto força a presença do payload mesmo antes de o servidor tentar validar os dados lá dentro. As regras estruturais do próprio payload são geridas por um schema associado ao Media Type Object, embora a mecânica profunda do design de JSON Schema seja abordada no episódio dez. Aqui está a ideia principal. O Request Body Object separa o payload de dados brutos dos parâmetros de transporte HTTP, permitindo que um único endpoint aplique regras de validação completamente diferentes com base apenas no media type declarado no content map. É tudo por este episódio. Obrigado por ouvires e continua a desenvolver!

Olá, daqui é o Alex da DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 8 de 19. A maioria dos developers documenta o happy path, mas a verdadeira resiliência da API vem de definir rigorosamente como as coisas vão falhar. Se apenas disseres aos clients o que acontece quando tudo corre perfeitamente, a tua API está apenas meio documentada. Hoje, vamos olhar para Expectations e Error Responses. No OpenAPI, as responses servem como a garantia máxima do contrato. Elas formalizam a promessa de que, se o client enviar um request específico, a API vai devolver um payload conhecido ou um erro estruturado. Esta promessa é gerida pelo Responses Object. Pensa nisto como uma routing table para resultados. As keys neste map são HTTP status codes escritos como strings, como o texto "200" ou "404". Os values associados a essas keys são Response Objects individuais, que detalham exatamente o que volta para o client pela rede. Aqui está a ideia principal sobre a formatação destes objects. Em grande parte do OpenAPI, os campos description são completamente opcionais. Tu usas-os quando queres adicionar contexto útil para outros developers. Num Response Object, o campo description é estritamente obrigatório. Se o omitires, toda a tua definição de API fica inválida. Não precisa de ser um parágrafo longo. Uma frase curta e precisa a explicar o resultado é suficiente, mas o parser vai exigir a sua presença. Considera um cenário prático onde um client faz um request de um perfil de user específico. Para o resultado de sucesso, defines uma key para a string "200". Dentro desse Response Object, forneces a tua description obrigatória, talvez a dizer "Successful user retrieval". A seguir, defines o campo content. Este campo mapeia um media type, mais frequentemente "application/json", diretamente para o schema que define a estrutura do teu user object. O código do client agora sabe exatamente que properties esperar quando a chamada tem sucesso. Isso cobre o resultado esperado. Agora tens de documentar a falha. No mesmo Responses Object, defines outra key para "404". A description obrigatória pode ser simplesmente "User não encontrado". Tal como no caso de sucesso, o campo content aqui mapeia "application/json" para um schema, mas desta vez aponta para a tua estrutura de erro padronizada. Graças a este contrato explícito, a aplicação client pode fazer parse com segurança da error response e mostrar um prompt útil ao end user, em vez de crashar com dados inesperados. Vai haver sempre casos em que não consegues prever todos os error codes que a tua arquitetura pode gerar. Um reverse proxy pode lançar um 502 Bad Gateway, ou uma web application firewall pode injetar um 403 Forbidden. É aqui que entra o wildcard default. Em vez de um HTTP status code numérico, usas a palavra exata "default" como key. Isto funciona como uma definição catch-all. Se o server devolver qualquer status code que não tenhas listado explicitamente no Responses Object, o client faz fallback para a estrutura definida em default. Isto funciona como uma safety net para error handling genérico, garantindo que o client continua a saber como ler o error payload. Uma definição de API verdadeiramente robusta não explica apenas o cenário perfeito; fornece um mapa preciso e previsível para todas as formas possíveis de o sistema falhar. Obrigado por passares uns minutos comigo. Até à próxima, fica bem.

Olá, daqui fala o Alex da DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 9 de 19. Se a tua API tem 100 endpoints e todos devolvem exatamente a mesma estrutura de paginação, fazer copy-paste é uma receita para o desastre. Uma pequena alteração no nome de um field significa ter de procurar manualmente 100 definições espalhadas pelo teu documento. O mecanismo estrutural que resolve esta tensão é a Reusability com Components. A especificação OpenAPI resolve o spec bloat através de uma secção dedicada de root-level chamada Components Object. Pensa nele como um dicionário centralizado ou uma library interna para a definição da tua API. Em vez de definires estruturas de dados complexas, query parameters standard, ou respostas de server repetitivas inline debaixo de cada path individual, declaras tudo exatamente uma vez dentro do Components Object. Isto estabelece uma single source of truth estrita. Antes de explicar a mecânica, preciso de esclarecer um equívoco comum sobre como esta secção se comporta. Definir um schema, um header ou um parameter dentro do Components Object não o expõe automaticamente na documentação da tua API ou na tua routing logic. A secção components é totalmente passiva. Não tem efeito direto nos teus endpoints. Um component só importa se um path ou operation real apontar explicitamente para ele. Para chamares um component ao serviço ativo, usas o Reference Object. Na sintaxe OpenAPI, isto é representado pela keyword dollar-sign-ref. O Reference Object usa um JSON Pointer para dizer ao tooling exatamente onde localizar a definição partilhada. Uma pointer string interna standard começa com um símbolo de hash, seguido de uma slash, a palavra components, outra slash, o nome da categoria específica e, finalmente, o nome personalizado que deste ao teu object. Vamos analisar isto num cenário concreto. Quase qualquer API requer uma forma consistente de devolver erros de client e de server. Queres que as tuas respostas 400 Bad Request e 500 Internal Server Error partilhem exatamente a mesma estrutura em todos os endpoints, talvez contendo um error code integer e uma message string descritiva. Primeiro, navegas até ao teu root Components Object. Lá dentro, abres uma categoria chamada schemas. Debaixo de schemas, defines um novo object genérico chamado ErrorModel e especificas as tuas properties code e message. A tua estrutura de erro genérica está agora guardada em segurança. De seguida, sobes para os paths da tua API. Quando defines a resposta de nível 400 para um endpoint de criação de utilizador, ignoras completamente escrever as properties do schema inline. Em vez disso, forneces uma key dollar-sign-ref. O seu valor é o path exato para o teu schema guardado: hash slash components slash schemas slash ErrorModel. Inseres exatamente a mesma reference string na resposta de nível 500. Repetes esta referência pelos teus endpoints de faturação, teus endpoints de autenticação e teus endpoints de pesquisa. Dezenas de operations apontam agora para uma única definição. Esta estratégia organizacional vai muito além dos schemas. O Components Object fornece categorias específicas para vários elementos da API. Podes guardar argumentos de paginação standard dentro da categoria parameters. Podes definir estruturas de payload inteiras em requestBodies, ou requisitos de autorização standard em securitySchemes. A lógica operacional permanece idêntica em todos eles. Define o object uma única vez no seu bucket correspondente e, de seguida, liga-o aos teus paths operacionais usando uma referência. Aqui está o insight chave. Construir uma especificação de API maintainable é fundamentalmente sobre controlar a duplicação. Quando surge um novo requisito que te obriga a adicionar um field de timestamp a cada resposta de erro, utilizar components significa que editas o ErrorModel em exatamente um lugar, e todas as operations em toda a tua API herdam automaticamente a atualização. É tudo por agora. Até à próxima!

Olá, daqui fala o Alex da DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 10 de 19. Sabes o que é um integer, mas a tua base de dados precisa de saber se é um valor de 32 ou 64 bits. Os schemas preenchem essa lacuna. Este episódio é inteiramente sobre Data Types e Schemas. O Schema Object atua como um motor de validação rigoroso para a tua API. Fica diretamente por baixo dos teus parameters, request bodies e responses. Em vez de simplesmente dizeres a um cliente para enviar um payload JSON genérico, um schema dita a forma, o tipo e os limites exatos desses dados. Atua como um filtro rigoroso na fronteira do teu sistema. Se um request recebido não corresponder às regras definidas no schema, falha a validação antes mesmo de a lógica da tua aplicação o ver. Historicamente, os developers encontravam um grande ponto de atrito ao definir estas regras. A versão 3.0 do OpenAPI usava o seu próprio dialeto personalizado de JSON Schema. Era próximo do standard, mas fundamentalmente incompatível em alguns aspetos frustrantes, causando inúmeras dores de cabeça com o tooling. A versão 3.1 do OpenAPI resolve isto completamente. Já não é um dialeto personalizado. O OpenAPI 3.1 está agora totalmente alinhado com o JSON Schema moderno. Especificamente, atua como um superset do JSON Schema Draft 2020-12. Isto significa que qualquer documento JSON Schema standard que já tenhas é automaticamente um schema OpenAPI 3.1 válido. Ser um superset significa simplesmente que o OpenAPI adiciona algumas keywords específicas de API, como identificadores de configuração XML, sem quebrar o standard subjacente. No cerne destas regras de schema está a keyword type. O OpenAPI baseia-se nos tipos de dados primitivos definidos pelo JSON Schema. Tens strings, integers, numbers e booleans. A distinção entre number e integer é estritamente aplicada. O tipo number lida com valores floating-point e doubles, enquanto o tipo integer rejeita especificamente qualquer coisa com uma fração decimal. Aqui está o ponto chave. Saber que algo é simplesmente uma string ou um integer raramente é contexto suficiente para um sistema de backend. É aqui que o modificador format se torna essencial. A keyword format restringe um tipo primitivo abrangente a algo específico para o qual o teu código pode alocar memória ou validar. O tipo primitivo diz ao parser JSON como ler os dados raw, e o format diz à tua aplicação exatamente como interpretar o valor. Por exemplo, se definires uma propriedade como um integer, podes adicionar um format de int32 ou int64 para especificar o seu tamanho exato em bytes. Se o teu tipo for uma string, podes aplicar um format como date-time, password ou email. A especificação OpenAPI define um registry standard destes formats, mas o campo é, em última análise, uma open string, o que significa que o tooling pode suportar formats customizados se a tua aplicação os exigir. Vamos analisar um cenário concreto. Precisas de definir um objeto User para um endpoint de registo. Começas por criar um schema do tipo object. Dentro deste objeto, defines duas propriedades, um ID e um endereço de email. Para a propriedade ID, defines o type como integer e o format como int64. Para a propriedade de endereço de email, defines o type como string e o format como email. Por fim, especificas um array de propriedades required contendo os nomes de ambos os campos, ID e email. Agora tens um contrato estrito e executável. Se um cliente enviar uma propriedade de email que não se assemelhe a um endereço de email válido, ou um ID que exceda o limite numérico de 64 bits, o API gateway ou a framework rejeita o payload imediatamente. A precisão na fronteira da API poupa-te o trabalho de escrever lógica interminável de verificação de dados dentro dos teus controllers. É tudo por este episódio. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui é o Alex da DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 11 de 19. Antes de poderes proteger um endpoint sensível, tens de declarar formalmente como é exatamente um crachá de identificação válido. Não podes simplesmente exigir autenticação a um client. Tens de especificar o mecanismo exato que ele tem de usar, os URLs a que tem de aceder e os parâmetros que tem de enviar. Definir security schemes é como resolves isto. Pensa neste passo como fazer um inventário das fechaduras que existem no teu sistema. Estás a descrever os tipos de fechaduras disponíveis, mas ainda não as estás a instalar em nenhuma porta específica. No OpenAPI, defines estas fechaduras dentro do objeto components, especificamente numa secção chamada security schemes. Cada fechadura recebe um nome de referência personalizado à tua escolha. Dentro desse nome personalizado, declaras o seu type e as suas properties obrigatórias. Existem cinco types principais de security schemes na especificação OpenAPI três ponto um. O primeiro é o type http. Isto abrange os mecanismos de autenticação HTTP standard definidos pelo RFC 7235, como a autenticação Basic ou Bearer. Para definires um scheme de token Bearer HTTP standard, crias uma entrada em security schemes. Defines a property type para a string http, e defines a property scheme para a string bearer. Podes também, opcionalmente, adicionar uma property bearer format para dar uma pista sobre o tipo de token, como fornecer a string JWT. Aqui está o ponto chave. Quando usas o scheme http bearer, a especificação assume implicitamente que o token será enviado no header de Authorization HTTP standard. Não dizes ao OpenAPI onde procurar. Mas o segundo type, o scheme api key, é completamente diferente. Para uma API key, tens de especificar explicitamente tanto a property name, que é o nome exato do campo, como a property in, que dita para onde a chave vai. A property in apenas aceita três valores: query, header, ou cookie. Se estás à espera de um header customizado como X API Key, usa o type api key. Se estás a usar headers de Authorization standard, usa o type http. O terceiro type é oauth2. Este requer uma configuração mais estrutural porque o OAuth2 tem múltiplos flows distintos. Para definires um authorization code flow complexo de OAuth2, começas por definir o type como oauth2. Depois, forneces um objeto flows. Dentro de flows, adicionas um objeto authorization code. Este objeto aninhado requer dois URLs específicos. Forneces o authorization url onde o utilizador faz login, e o token url onde a aplicação troca um code por um token. Tens também de fornecer um objeto scopes, que mapeia nomes de scope específicos para descrições de texto curtas do que esses scopes permitem. O quarto type é open id connect. Este é muito mais simples de declarar do que o OAuth2. Defines o type como open id connect e forneces uma única property open id connect url. Isto aponta diretamente para o well-known discovery document que os clients usam para se configurarem automaticamente. Finalmente, o quinto type é mutual t l s, que significa mutual Transport Layer Security. Simplesmente defines o type como mutual t l s. Isto sinaliza que o client tem de fornecer um certificado X 509 durante o handshake TLS inicial para autenticar, inteiramente fora da application layer HTTP. A principal conclusão aqui é que definir security schemes separa o mecanismo de autenticação dos endpoints que o exigem. Constróis as tuas fechaduras uma vez num catálogo centralizado, garantindo que os clients sabem exatamente como formatar as suas credenciais antes sequer de tentarem bater à porta. Já agora, se quiseres apoiar o programa, podes procurar por DevStoriesEU no Patreon. É tudo por este episódio. Obrigado por ouvires, e continua a programar!

Olá, daqui é o Alex do DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 12 de 19. Aplicar segurança é um ato de equilíbrio: queres trancar todo o cofre globalmente, mas deixar o lobby aberto para visitantes. Para fazeres isso sem ficares trancado do lado de fora, precisas de perceber como o OpenAPI aplica os Security Requirements. Depois de definires os teus security schemes na secção de components do teu documento OpenAPI, tens de os associar aos teus endpoints. Fazes isso usando o security array. Este array contém Security Requirement Objects, que referenciam os nomes dos schemes que criaste anteriormente. Podes declarar este security array em dois lugares: globalmente, na raiz do teu documento OpenAPI, ou localmente, dentro de um Operation Object específico. Se o definires na raiz, todos os endpoints da tua API herdam esse requisito. Se o definires dentro de uma operation, faz um override completo à configuração global. Não faz merge com as definições globais, substitui-as totalmente. Imagina um cenário em que defines um requisito global de que todas as routes da API precisam de um Bearer token. Isso protege o cofre. Mas também tens uma route de login. Se a route de login herdar esse requisito global de token, os novos utilizadores nunca se conseguem autenticar porque ainda não têm um token. Tens de fazer override a esse bloqueio global. Um erro comum é simplesmente omitir o campo security na operation de login, assumindo que isso significa que não há segurança. Se deixares o campo de fora, a operation assume o requisito global por defeito, e os teus utilizadores ficam bloqueados. Para permitires explicitamente o acesso anónimo, tens de definir o security array na operation de login e colocar um empty object lá dentro. Esse empty object diz ao OpenAPI que o requisito para aceder a este endpoint específico é absolutamente nenhum. O bloqueio global é ignorado, e os visitantes podem aceder ao lobby. É aqui que a coisa fica interessante. A forma como estruturas os itens no security array dita a lógica da tua autenticação. Isto lida com cenários de logical OR e logical AND baseando-se puramente nos limites dos objects. Se o teu array contiver dois Security Requirement Objects separados, por exemplo, um object a pedir uma API key e um segundo object separado a pedir OAuth2, isso cria um logical OR. A API vai aceitar uma request se o client satisfizer o primeiro object ou o segundo object. Se precisares de um logical AND, mudas os limites. Vamos supor que uma request tem de ter tanto um token OAuth2 como uma custom header signature. Colocas os nomes desses dois schemes dentro de um único Security Requirement Object. Como partilham o mesmo object, a API exige que todos sejam válidos antes de deixar a request passar. Quando escreves estes objects, mapeias o nome do teu scheme para um array. Se estiveres a usar OAuth2 ou OpenID Connect, esse array lista os scopes específicos necessários para a operation, como ler ou escrever dados. Se estiveres a usar uma API key ou um basic HTTP scheme, os scopes não se aplicam, por isso tens de mapear o nome do scheme para um empty array para satisfazer a specification. A estrutura física do teu security array é a tua principal ferramenta para definir a lógica de acesso. Domina a diferença de limites entre listar itens no array versus listar itens dentro de um único object, e poderás criar qualquer authentication flow que o teu sistema precise. É tudo por este episódio. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui é o Alex da DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 13 de 19. O REST é ótimo para fazer perguntas, mas o que acontece quando a tua API precisa de ser ela a iniciar a conversa? As APIs assíncronas com webhooks resolvem isto fazendo push de dados no momento em que um evento ocorre, eliminando completamente a necessidade de polling constante. Historicamente, os consumidores tinham de escrever scripts que verificavam repetidamente os teus endpoints para ver se um status tinha mudado. Isto era ineficiente tanto para os servidores deles como para os teus. O OpenAPI 3.1 resolveu esta limitação ao introduzir o campo webhooks logo na root do documento OpenAPI. Esta adição trouxe suporte de primeira classe para comunicação assíncrona e event-driven para as especificações standard de APIs. Em vez de documentares apenas o que um cliente envia para o teu servidor, o campo webhooks permite-te documentar exatamente o inverso. Tu defines os requests HTTP que a tua plataforma vai iniciar e enviar para o servidor do consumidor. É necessário traçar uma linha clara entre webhooks e callbacks, pois a especificação OpenAPI trata-os de formas muito diferentes. A distinção está na forma como o URL de destino é registado. Os callbacks são acionados por um request de API específico e ativo. Um cliente acede a um endpoint de subscrição na tua API e fornece um URL de destino logo ali no payload do request. Como estão ligados a uma operação, os callbacks são definidos dentro desse operation object específico. Os webhooks são registados out-of-band. Um developer faz login num dashboard de gestão, navega até uma página de settings e cola o seu URL de destino num formulário. A especificação da API não quer saber como o URL foi obtido. Como os webhooks existem independentemente de qualquer chamada de API específica em runtime, eles são colocados no nível mais alto do teu documento OpenAPI, lado a lado com os teus paths e components standard. Para documentares um webhook, abres o map de webhooks ao nível da root. Cada key dentro deste map é uma string simples que dá o nome ao evento. Por exemplo, podes usar a string payment dot successful. O valor associado a essa key é um Path Item Object standard. Esta é exatamente a mesma estrutura que usas para definir os teus endpoints REST normais. Dentro desse Path Item Object, declaras o método HTTP que a tua plataforma vai usar para entregar o evento, que é quase sempre um request POST. Aqui está o ponto chave. A perspetiva é completamente invertida, mas as ferramentas continuam a ser idênticas. Usas schema objects standard para definir o request body que a tua plataforma vai enviar. No cenário do payment dot successful, especificas que o payload será um objeto JSON contendo um ID de pagamento único, o valor exato cobrado e um timestamp. Também podes definir headers, o que é crucial para webhooks, porque geralmente precisas de documentar um header de assinatura criptográfica para que o consumidor possa verificar se o payload veio mesmo de ti. Por fim, documentas as responses que esperas receber de volta do consumidor. Podes declarar que o teu sistema espera um status code 200 OK dentro de três segundos, caso contrário, o teu sistema vai fazer retry da entrega mais tarde. Ao padronizar esta documentação reversa de API, dás aos consumidores tudo o que eles precisam para gerar o seu próprio server code. Eles sabem exatamente que payload fazer parse, que headers validar e que status codes retornar. O campo webhooks ao nível da root muda o API design de simples interações request-response para uma arquitetura event-driven totalmente documentada. É tudo por este episódio. Obrigado por ouvires, e continua a programar!

Olá, daqui é o Alex da DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 14 de 19. Criar um utilizador é o primeiro passo, mas como é que um client automatizado sabe intuitivamente onde ir fazer fetch do perfil desse utilizador a seguir? Podes fazer hardcode do workflow no código do teu client, mas isso rebenta no momento em que a estrutura da tua API muda. A solução para isto são State Transitions com Links. No OpenAPI, o objeto Link fica dentro de uma response e mapeia dados dessa response para os parameters de outra operation. Para ser perfeitamente claro, os links não executam requests automaticamente. Não transformam o OpenAPI num motor de orquestração ativo. Simplesmente fornecem instruções estáticas ao teu tooling, SDKs ou documentação sobre como construir a próxima request lógica num workflow. Se já construíste APIs antes, podes pensar que isto soa exatamente a HATEOAS estrito, onde o servidor envia links hypermedia dinâmicos dentro do payload da response. Os links do OpenAPI oferecem uma alternativa developer-friendly a essa abordagem. Em vez de forçar o backend a injetar URIs dinâmicos em cada response em runtime, os links do OpenAPI descrevem as state transitions do workflow de forma estática dentro da própria definição da API. As tools do client conseguem entender o workflow sem precisarem de fazer parse a payloads em tempo real para descobrir que ações são possíveis. A lógica flui ligando uma response de origem a uma operation de destino. Considera uma request POST standard usada para criar um novo utilizador. A response devolve um JSON body com um ID de utilizador recém-gerado. Dentro dessa definição de response específica, adicionas um map de links. Cada entrada neste map define uma relação com outra operation, como a request GET que vai fazer fetch do perfil do utilizador. Identificas a operation de destino usando um de dois campos mutuamente exclusivos. O primeiro é o operation ID, que é uma string simples que corresponde ao identificador único da operation de destino. O segundo é a operation reference, que usa um JSON Pointer standard para navegar no documento OpenAPI e localizar o path de destino e o método HTTP. O operation ID é geralmente mais limpo se a tua API os definir de forma consistente, enquanto a operation reference é útil para apontar para operations em documentos OpenAPI externos. Assim que apontas para a operation de destino, tens de lhe fornecer os dados corretos. Fazes isso usando um map de parameters. As keys neste map representam os nomes dos parameters que a operation de destino espera, como o path parameter do ID do utilizador. Os values são runtime expressions que dizem ao tooling de onde extrair esses dados no contexto atual. Uma runtime expression é uma sintaxe específica que avalia dados durante a chamada à API. Podes escrever uma expression que instrui o client a olhar para o response body, localizar o campo ID e extrair o seu valor. Não estás limitado ao response body. As runtime expressions podem extrair values dos response headers, do path da request original ou dos query parameters da request original. Se a operation de destino exigir um request body em vez de apenas parameters, o objeto Link fornece um campo request body. Isto permite-te mapear uma runtime expression diretamente no payload da request subsequente. Quando um gerador de SDKs processa estes links, pode criar automaticamente chamadas de métodos encadeadas, permitindo a um developer criar um utilizador e chamar imediatamente um método gerado para fazer fetch do perfil no objeto devolvido. Aqui está o ponto-chave. O verdadeiro poder do objeto Link é que faz a ponte entre endpoints isolados, transformando um dicionário plano de API paths num map navegável de ações que os teus clients podem seguir com confiança, sem dependerem de hardcoded URLs. Obrigado por ouvires — até à próxima!

Olá, daqui é o Alex do DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 15 de 19. Uma especificação JSON perfeitamente elaborada é inútil se os developers que consomem a tua API se recusarem a lê-la. Precisas de a tornar visual. É exatamente aí que as Interactive Docs com o Swagger UI entram em cena. Até agora, tratámos um documento OpenAPI como um ficheiro de texto bruto que contém endpoints e schemas. O Swagger UI pega nesse ficheiro JSON ou YAML e traduz-o numa página web interativa. Isto muda completamente o foco de escrever a especificação para a consumir ativamente. Os developers podem navegar pelos endpoints, inspecionar query parameters, e executar live HTTP requests diretamente do seu browser. Atua como uma ponte entre um contrato estático e uma ferramenta de live testing. Se quiseres alojar esta interface tu mesmo, provavelmente vais começar pelo Node Package Manager. Quando o fores instalar, vais deparar-te imediatamente com uma armadilha comum de nomenclatura. Existem dois packages principais. O primeiro chama-se simplesmente swagger hífen ui. Não uses este, a não ser que estejas a correr uma build tool como o Webpack ou o Rollup para compilar uma aplicação de front-end customizada. Se o teu objetivo é apenas alojar a documentação diretamente, precisas do package chamado swagger hífen ui hífen dist. O sufixo dist significa distribution. Contém os static assets pré-construídos e prontos a servir, como os bundles de JavaScript principais, stylesheets de CSS, e um ficheiro index HTML. Colocas estes ficheiros em qualquer web server básico, e eles funcionam imediatamente. Se não quiseres gerir node packages ou ficheiros locais de todo, podes fazer embed desses mesmos static assets numa página web vazia usando uma content delivery network como o unpkg. Adicionas uma style tag HTML standard a apontar para o ficheiro CSS do Swagger UI no unpkg, e uma script tag para o bundle de JavaScript. Depois, escreves um pequeno bloco de inicialização em JavaScript que aponta para o endereço web onde o teu ficheiro OpenAPI está. O browser carrega a página vazia, faz fetch dos assets da rede, vai buscar a tua especificação, e renderiza a interface completa automaticamente. Aqui está o ponto chave. Nem precisas de escrever HTML para fazer deploy desta interface. O método mais limpo e escalável é usar a imagem oficial do Docker. Simplesmente fazes pull da imagem chamada swaggerapi barra swagger hífen ui. Corrê-la completamente out of the box vai carregar um exemplo default da Petstore. Para servires o teu próprio ficheiro local em vez disso, montas a tua especificação no container como um volume. Depois, passas uma environment variable chamada SWAGGER underscore JSON, a apontar para o path exato onde montaste esse ficheiro dentro do container. Primeiro, executas o comando Docker run e mapeias uma exposed port como a oitenta para a tua máquina local. A seguir, mapeias a tua diretoria local que contém o teu ficheiro swagger ponto json para uma diretoria dentro do container. Finalmente, defines a environment variable SWAGGER underscore JSON para apontar para esse file path interno específico. Quando o container arranca, ele levanta um web server leve, lê a tua environment variable para localizar a especificação, e serve a UI. Ficas com um portal de documentação totalmente funcional a correr em segundos, sem instalares uma única dependência local. Ao fazer o decoupling do rendering da documentação do próprio source code da API, o Swagger UI transforma um contrato de texto estático num testing environment executável que viaja perfeitamente por qualquer infraestrutura. Obrigado por passares uns minutos comigo. Até à próxima, fica bem.

Olá, daqui é o Alex da DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 16 de 19. A documentação da tua API demora dez segundos a carregar e, sempre que um engenheiro quer mostrar um endpoint específico a um colega, tem de escrever instruções manuais sobre como fazer scroll para baixo e encontrá-lo. As definições default foram feitas para ser alteradas. Vamos ajustar a interface para que os teus developers encontrem exatamente o que precisam em milissegundos. Isto é tudo sobre personalizar o Swagger UI. Antes de ajustar o que quer que seja, precisamos de traçar uma linha bem definida. As definições que vamos discutir não entram no teu documento de especificação OpenAPI. Estas são configurações de runtime. Estás a modificar a interface que renderiza o documento, não o documento em si. Podes injetar estes parâmetros de duas maneiras. Se estiveres a fazer o host dos ficheiros da UI tu mesmo, passas um objeto de configuração para o construtor Javascript do Swagger UI quando a página web carrega. Se estiveres a usar a imagem Docker oficial do Swagger UI, passas exatamente estas mesmas propriedades diretamente para o container como environment variables. A definição mais fundamental diz à interface onde encontrar a tua spec. Se tiveres uma única API, usas o parâmetro chamado url, no singular, e passas-lhe uma string com o path. Mas se tiveres uma arquitetura de microservices com várias APIs distintas, usas o parâmetro urls, no plural. Passas-lhe um array contendo objetos, cada um com um name e um link. Isto gera automaticamente um dropdown menu na barra superior da interface, permitindo ao utilizador alternar entre diferentes definições de API de forma fluida. Agora, considera uma API enterprise gigante com centenas de paths e data models complexos. Se o Swagger UI tentar renderizar tudo isso no ecrã de uma só vez, o browser vai bloquear. O parâmetro que controla isto é o docExpansion. Por default, está definido para a palavra list, que expande todas as tags de top-level, mas esconde os detalhes da operação. Podes alterá-lo para full, o que expande absolutamente tudo na página. No entanto, para poupar tempo de load numa API gigante, vais querer definir o docExpansion para none. Isto força a interface a carregar completamente colapsada. Poupa imensa memória e renderiza instantaneamente, permitindo ao utilizador abrir apenas o que realmente precisa. Assim que o utilizador encontrar o que precisa, vai querer partilhar. Por default, clicar nas operações no Swagger UI não altera a barra de endereços do browser. Se definires o parâmetro deepLinking para true, a interface adiciona um hash fragment ao URL sempre que um utilizador expande um endpoint ou uma tag. Os teus developers podem copiar esse URL exato e enviá-lo a um colega, direcionando-o precisamente para uma operação específica em vez do topo da página. Aqui está o ponto chave. Se a tua documentação existe principalmente para servir de sandbox, vais querer reduzir a fricção. Normalmente, um utilizador tem de clicar num botão chamado Try it out numa operação para desbloquear os input fields. Se definires a flag tryItOutEnabled para true, esses input fields ficam ativos no momento em que a operação é expandida. O utilizador pode simplesmente escrever e executar sem esse clique extra. Personalizar o Swagger UI em runtime dá-te o poder de moldar a experiência de documentação à volta da intenção do utilizador, transformando um render genérico numa ferramenta de alta performance feita à medida para a tua equipa. Obrigado por ouvirem. Fiquem bem, pessoal.

Olá, daqui é o Alex da DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 17 de 19. Escrever specs OpenAPI à mão num editor de texto normal é um pesadelo de typos e brackets desalinhados. Precisas de um ambiente que grite contigo no milissegundo em que indentes um path incorretamente. É exatamente isso que o Designing with Swagger Editor te dá. O Swagger Editor não é apenas uma caixa de texto. É um Integrated Development Environment criado especificamente para o standard OpenAPI. A sua principal função é ajudar-te a desenhar, definir e documentar a tua API de raiz. O layout é dividido. O lado esquerdo contém o teu código YAML ou JSON raw. O lado direito mostra a documentação interativa renderizada. Aqui está o ponto chave. O editor valida a tua sintaxe contra a spec OpenAPI em tempo real. Se escreveres mal o nome de um objeto ou te esqueceres de um campo obrigatório, ele sinaliza o erro instantaneamente, dizendo-te exatamente que linha está a falhar. Não precisas de correr um build script separado para descobrir que a tua indentação está errada. Precisamos de esclarecer uma coisa em relação às versões. O Swagger Editor clássico, conhecido como versão 4, é uma ferramenta legacy. Ele suporta totalmente o OpenAPI 2.0 e 3.0. Não foi construído nativamente para o OpenAPI 3.1.0. Se colares uma spec 3.1.0 no editor clássico, a validação vai falhar. Para specs 3.1.0 modernas, tens de mudar para o Swagger Editor Next, que vamos abordar no final. Mas para trabalho standard em 3.0, o editor clássico continua profundamente enraizado em muitos workflows. Podes usar o editor clássico diretamente no teu browser sem instalar nada. No entanto, colar designs de API proprietários num site público é uma maneira rápida de irritar a tua equipa de segurança. É aqui que entra a execução local. Podes correr o Swagger Editor localmente na tua própria máquina. Podes instalá-lo usando o npm, fazendo pull do package swagger-editor e iniciando um servidor local. Uma abordagem ainda mais limpa é usar Docker. Fazes pull da imagem swaggerapi barra swagger-editor, e levantas um container mapeado para o teu port local. Isto corre exatamente o mesmo editor visual inteiramente na tua máquina. Este setup permite que as equipas desenhem com segurança atrás de uma firewall corporativa sem expor specs não lançadas à internet pública. Toda a validação em tempo real acontece localmente. Como o editor fornece feedback visual instantâneo, tu desenhas mais rápido. Mapeias os teus paths, defines os teus modelos de dados e verificas imediatamente se a documentação resultante faz sentido. Apanhas erros estruturais durante a fase de design, muito antes de escreveres a tua lógica de backend. Se estás a achar estes episódios úteis, podes apoiar o programa procurando por DevStoriesEU no Patreon. O aspeto mais valioso do editor é a confiança imediata que ele proporciona; uma spec sem erros no ecrã garante que as tuas ferramentas downstream vão funcionar sem problemas. É tudo por este episódio. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui é o Alex da DEV STORIES DOT EU. Ecossistema OpenAPI e Swagger, episódio 18 de 19. Passaste horas a desenhar a especificação perfeita. Agora, vê-a escrever milhares de linhas de código de servidor para ti em três segundos. Essa é a recompensa de automatizar com o Swagger Codegen. Primeiro, precisamos de esclarecer uma armadilha comum de versioning. A versão dois do Swagger Codegen suporta exclusivamente as especificações Swagger 2.0 mais antigas. Se estás a usar o standard moderno OpenAPI 3.0, tens de usar o Swagger Codegen versão três. Este episódio foca-se inteiramente na versão três. O Swagger Codegen é um engine baseado em templates que lê o teu documento OpenAPI e constrói automaticamente o código da aplicação. Ele traduz os teus ficheiros de design em classes, interfaces e operações de rede reais. Esta é a recompensa máxima do desenvolvimento design-first. Em vez de escreveres manualmente centenas de ficheiros boilerplate para routing HTTP, parsing de parâmetros e object models, deixas a máquina tratar do trabalho repetitivo. O gerador produz dois tipos principais de código. Primeiro, constrói client SDKs. Se precisas de um client em Python, JavaScript ou Go para falar com a tua API, o Codegen cria uma library pronta a usar. O package do client trata automaticamente dos HTTP requests, da formatação de URLs e do parsing das responses. Os developers de frontend ou outras equipas de microservices podem simplesmente fazer import desta library gerada e chamar métodos nativamente, em vez de criarem network requests à mão. Segundo, gera server stubs. Um server stub é a estrutura básica da tua aplicação de backend. Inclui o routing da API, os data models e as layers de validação de input. Ele liga tudo para que o servidor possa arrancar e ouvir tráfego imediatamente. O código gerado interceta os HTTP requests recebidos, valida o payload contra o teu schema OpenAPI e passa os dados limpos para uma função vazia. O teu único trabalho como developer é preencher essas funções vazias com a tua business logic real, como database queries ou cálculos. Vamos ver como corres isto na prática. O Swagger Codegen é geralmente executado através de uma command-line interface usando um ficheiro Java archive. Abres o teu terminal e corres o comando Java com a flag traço jar, a apontar para o ficheiro swagger-codegen-cli ponto jar. Dás-lhe o comando generate. A seguir, forneces três flags essenciais. Usas traço i para especificar o teu ficheiro de input, como openapi ponto yaml. Usas traço l para definir a tua linguagem e framework de destino. Por exemplo, passar spring diz à tool para construir uma aplicação Java Spring Boot. Finalmente, usas traço o para especificar o diretório de output de destino. Executas o comando. Em poucos segundos, a tool faz o parsing da especificação. Mapeia cada string, integer e array definidos no teu documento OpenAPI para os tipos nativos equivalentes em Java. Depende de uma library de templates lógicos pré-construídos para a framework de destino para unir estes tipos. O resultado é uma estrutura de diretórios completa, cheia de controllers, ficheiros de configuração e data classes. Podes compilar esse diretório de output imediatamente, arrancar o servidor e aceder com sucesso aos endpoints que desenhaste. Aqui está o ponto-chave. A geração de código não poupa apenas tempo no início. Ao guiar a estrutura do teu servidor e as tuas client libraries diretamente a partir do mesmo ficheiro OpenAPI, garantes que a tua implementação corresponde perfeitamente ao teu contract, reduzindo a zero os erros de integração entre equipas. É tudo por este episódio. Obrigado por ouvires, e continua a desenvolver!

Olá, daqui fala o Alex da DEV STORIES DOT EU. OpenAPI e o Ecossistema Swagger, episódio 19 de 19. As APIs REST já não são a única forma de comunicação entre sistemas. Chegou a hora de uma ferramenta que entenda Kafka e arquiteturas event-driven tão bem como HTTP. Essa ferramenta é o Swagger Editor Next. Também conhecido como versão 5, este é um rebuild completo da interface standard que talvez já conheças. O Swagger Editor clássico está profundamente ligado a APIs HTTP síncronas e a técnicas de rendering mais antigas. Funciona bem com OpenAPI 3.0, mas pode bloquear ou ter lag ao validar ficheiros excecionalmente grandes. O Swagger Editor Next substitui essa infraestrutura obsoleta. É construído inteiramente sobre uma stack moderna de React e Webpack. Esta é a parte que interessa. O text input subjacente é agora alimentado pelo Monaco Editor. Esta é exatamente a mesma tecnologia que corre no Visual Studio Code. Por depender do Monaco, o Swagger Editor Next lida com ficheiros de especificação enormes sem falhas. Oferece um syntax highlighting robusto, deteção imediata de erros e validação precisa ao nível da linha, que simplesmente ultrapassa a versão clássica. Estás efetivamente a escrever num IDE leve, em vez de num web form. Isto cobre o engine. E quanto às especificações em si? O Swagger Editor Next traz duas grandes capacidades nativas. Primeiro, suporta OpenAPI 3.1.0 out of the box. Esta versão específica do OpenAPI está totalmente alinhada com o JSON Schema, o que significa que podes construir data models e componentes reutilizáveis muito mais complexos do que conseguias na versão 3.0. Segundo, o Swagger Editor Next renderiza nativamente especificações AsyncAPI. Este é o caminho definitivo a seguir para os developers que lidam com microservices event-driven em conjunto com as APIs tradicionais. O AsyncAPI usa uma estrutura muito semelhante à do OpenAPI, mas, em vez de definir paths HTTP e requests GET, documenta message brokers, topics e eventos assíncronos. Para veres como isto funciona na prática, imagina uma rede de uma smart city a gerir a iluminação pública. Se tivesses apenas ferramentas para REST, poderias tentar forçar um endpoint HTTP POST a representar uma stream constante de dados de sensores. Com o Swagger Editor Next, basta escreveres um documento AsyncAPI. Defines um channel chamado smart-city-streetlights. Atribuis o Kafka como protocol. Depois, especificas uma operação de publish que detalha a estrutura JSON exata que o sensor emite quando uma luz se acende. Enquanto escreves a tua especificação no lado esquerdo do ecrã, o Monaco Editor valida a sintaxe AsyncAPI. No lado direito, a interface renderiza um documento visual estruturado e interativo. Exibe claramente os topics do Kafka, os payloads esperados das mensagens e os headers do protocol. Já não precisas de toolchains separadas para as tuas APIs síncronas e para os teus microservices event-driven. O ecossistema evoluiu para lidar com ambos em simultâneo. A mudança para eventos assíncronos não significa começares do zero com a tua documentação; apenas requer um editor moderno capaz de ler esses novos standards. Como isto conclui a nossa série, tira um momento para ler a documentação oficial, carregar o Swagger Editor Next e tentares modelar um topic do Kafka tu mesmo. Se tiveres uma ideia para uma série completamente nova, visita devstories dot eu e diz-nos. Por agora é tudo. Até à próxima!