Documentar um software sempre foi um desafio no desenvolvimento de sistemas. Uma documentação incompleta gera uma experiência negativa em consumo de nossos serviços, com um maior número de erros, maior tempo para a compreensão das funcionalidades.

Em tempos não tão remotos, para se integrar com um serviço fornecido pelo banco era necessário ler PDFs com uma documentação extensa. Lembro quando trabalhei com desenvolvimento em Visual Basic 6 em uma fábrica de software, existia um manual apostilado que parecia com uma bíblia sobre integração de arquivos com bancos, mas felizmente hoje temos o Open API.

O que é o OpenAPI?

OpenAPI é uma linguagem padrão de mercado que é agnóstica de linguagem de programação, utilizada para descrever APIs REST e que permite de forma simples que máquinas e pessoas entendam quais serviços são oferecidos sem a necessidade de documentações extensas.

Por possuir informações essenciais para o negócio, esse é o primeiro documento que o desenvolvedor deverá analisar para entender quais serviços são oferecidos, o que deverá ser informado e o que será entregue.

Qual a diferença do OpenAPI e do Swagger?

Até 2015 a especificação foi renomeada de Swagger para OpenAPI. Essa mudança de nome gerou muita confusão, alguns chamavam de Swagger, outros de Open API e outros achavam que eram coisas diferentes.

Para entender melhor a diferença:

OpenAPI

É a especificação  originalmente baseada no Swagger e que foi doada pela SmartBear Software e hoje é mantida pela OpenAPI Iniciative, formado por um grupo de especialistas e organizações de diferentes áreas da tecnologia e que foca na criação, evolução e promoção de um formato neutro em relação a fornecedores.

Swagger

É o nome de algumas ferramentas utilizadas para implementar a especificação OpenAPI, sendo muito conhecido o SwaggerUI (utilizado para editar um e visualizar uma especificação), SwaggerHUB (utilizado para design e documentação de APIs). Apesar do Swagger possuir uma das ferramentas mais famosas, elas não são as única para escrever uma especificação OpenAPI.

Estrutura do OpenAPI

Basicamente uma especificação OpenAPI bem escrita nos fornecerá as seguintes informações:

– nome e descrição da API e de seus endpoints;

– informações de contato;

– endpoints e método de cada recurso oferecido pela API;

– forma de autenticação para acesso aos recursos;

– códigos de retorno na resposta;

– informações sobre campos e parâmetros, como nome, tipo, formato, obrigatoriedade e exemplos.

Abaixo vemos o exemplo de uma documentação OpenAPI

Benefícios

Por ser uma linguagem simples, ela é compreensível por pessoas não técnicas, facilitando o alinhamento entre áreas técnicas e áreas de negócio e ajudando a mitigar problemas de comunicação entre as áreas.

O OpenAPI também facilita os testes das APIs, visto que é importado facilmente em ferramentas como Postman e Insomnia e já traz os testes quase prontos, necessitando somente alguns ajustes como inclusão de credenciais.

Também é possível gerar bibliotecas em dezenas de linguagem de programação diferentes, reduzindo o tempo de desenvolvimento.

Como fazemos no BB

No BB, a especificação OpenAPI é o primeiro documento a ser escrito quando está sendo desenvolvido um serviço. A concepção de Contract First que é possível ao realizar a criação da especificação nesse momento ajuda o entendimento dos envolvidos do que será oferecido, informações necessárias e formato dos dados.

É um documento criado pelo time  de desenvolvimento com a área de negócio, com curadoria e apoio do Time de Gestão de APIs da Diretoria de Tecnologia e Diretória de Negócios Digitais.

Após a homologação por todos os envolvidos, o time de desenvolvimento inicia a construção dos serviços. Isso garante um menor tempo de construção e disponibilização aos parceiros, visto que o desenvolvedor já sabe o que será desenvolvido com base no OpenAPI e os times de negócio já iniciam a oferta dos serviços a parceiros, sabendo o que será disponibilizado.

Como se trata de uma linguagem de amplo conhecimento no mercado, percebemos uma melhora de experiência do cliente ao usar nossos serviços, diminuindo consideravelmente o tempo necessário para integração.

Assim vemos o OpenAPI como um meio de geração de negócios e entrega de valor para os nossos clientes e parceiros.

Mais informações sobre a especificação OpenAPI podem ser obtidas através do site oficial https://www.openapis.org/.

Leia também:

O BB onde você nem imagina: conheça as APIs do Banco do Brasil

O que é Banking as a Service (BaaS)?

Banking as a Service: perspectivas para o futuro do sistema bancário

Movimentos estratégicos: explorando o tabuleiro de xadrez do Domain-Driven Design

The post APIs: o uso da documentação das APIs appeared first on Blog do Banco do Brasil.