One of the best decisions we made at Coderockr was to adopt the "API First" approach for all the projects we started since 2010. However, in recent months, we recognized a need to improve the process of defining and documenting APIs. We were already using other approaches, but most of them involved documenting the API within the code itself, using annotations. This approach works, but it has some issues, especially when documentation needs to be altered by someone in business. Additionally, generating mocks and tests from these annotations is a complex challenge. With this in mind, we conducted some research and arrived at two alternatives: Swagger and API Blueprint. Both are API documentation standards and have their advantages and disadvantages:
Swagger: It is the market standard and has been adopted by several companies like Amazon. To describe the API, it is necessary to create JSON files, which greatly facilitates the process for programmers but is a bit complex for non-technical individuals to visualize and modify the content. There is a series of tools that can help with this process, but it has become a minor barrier for us. (Well, at least it's not YML... Did I mention that I hate YML?)
API Blueprint: This is a more recent specification created by a company called Apiary, which was acquired by Oracle. The major advantage of API Blueprint is that it is written in Markdown, making it much easier to edit the documents, even for those who are not familiar with coding. Additionally, there are several tools available that allow the generation of documents in the Swagger format, mock servers, and tests.
We opted for API Blueprint because of its ease of use and the agility it brought us. I will demonstrate with a small example. The definition is written in a file in Markdown format, which can be named “api.md” or “api.apib.” Both work, but if we use the .apib extension, we can take advantage of plugins for editors like Sublime Text that assist in writing. The plugins can be found on the official specification website.
FORMAT: 1A
HOST: http://api.sample.com.br/v1
# Sample da API
Descrição da Sample.
# Group API
## Sobre [/]
Aqui podemos descrever detalhes que são comuns a todos os serviços como formatos, headers, tipos de erros, etc
# Group Mensagem
## Mensagens [/message]
### Criar mensagens [POST]
+ Request Criar uma mensagem
+ Headers
Accept: application/json
Content-Type: application/json
+ Attributes (Message)
+ Response 201 (application/json)
+ Attributes (Created)
### Listar mensagens [GET]
+ Response 200 (application/json)
+ Attributes (array[Message])
+ Response 404 (application/json)
+ Attributes (Error)
## Mensagem [/message/{id_message}]
+ Parameters
+ id_message: 1 (number, required) - ID da mensagem
### Ver mensagem [GET]
+ Response 200 (application/json)
+ Attributes (Message)
+ Response 404 (application/json)
+ Attributes (Error)
### Excluir mensagem [DELETE]
+ Response 200 (application/json)
+ Attributes (Id)
+ Response 404 (application/json)
+ Attributes (Error)
### Alterar mensagem [POST]
+ Request Alterar uma mensagem
+ Headers
Accept: application/json
Content-Type: application/json
+ Attributes (Message)
+ Response 200 (application/json)
+ Attributes (Created)
+ Response 400 (application/json)
+ Attributes (Error)
## Anexos [/message/{id_message}/file]
+ Parameters
+ id_message: 1 (number) - ID da mensagem
### Listar anexos [GET]
+ Response 200 (application/json)
+ Attributes (array[File])
+ Response 404 (application/json)
+ Attributes (Error)
## Anexos [/message/{id_message}/file/{file_id}]
+ Parameters
+ id_message: 1 (number) - ID da mensagem
+ file_id: 1 (number) - ID do arquivo
### Ver anexo [GET]
+ Response 200 (application/json)
+ Attributes (File)
+ Response 404 (application/json)
+ Attributes (Error)
### Remover anexo [DELETE]
+ Response 200 (application/json)
+ Attributes (Id)
+ Response 400 (application/json)
+ Attributes (Error)
# Data Structures
## Message (object)
+ subject (string) - Assunto da mensagem
+ body (string) - Corpo da mensagem
## MessageUpdate (Message)
+ id_message (number) - Id da mensagem
## File (object)
+ id_file (number) - Id do arquivo
+ name (string) - Nome do arquivo
+ url (string) - Url do arquivo
## Created (object)
+ id (number) - Id gerado
## Id (object)
+ id (number) - Id a ser processado
## Error (object)
+ code: 400 (number) - Status code
+ message (string) - Mensagem do status
+ description (string) - Descrição do status
## Multi (object)
+ id (number) - Código da entidade
+ code: 200 (number) - Status code
+ message (string) - Descrição do status
## User (object)
+ id (number) - Código do usuário
+ name (string) - Nome do usuário
+ token (string) - Token do usuário conectado
On the specification website, you can see the details, but basically, what we do is define the URLs, the format of requests and responses. We can define simple and complex data structures and use them to describe what the API expects as input and what it should generate as output. The document is relatively simple to understand and modify, which was one of the key points in our choice. Even so, we can enhance the presentation.