The APIs has some services that can be consumed by any system, independently of the programming language used. But how to use that? So, to understand how the API works and how to use it is necessary to see documentation. And the swagger is a great option to document that

Swagger is an open source tool that helps developers to delivery a great API.

The documentation can be built manually or automatically. The first one is possible to do using swagger editor where de developer edits the file and then add that in the application.


Automatically, can be done using annotation which is built during the development.


An example is the API of job opportunity by restaurant where is possible see the structure. Next is showed an example of the annotation.

Example  1:

@ApiOperation(value = "Returns a List of Restaurant")                   
@ApiResponses( value =
    {  @ApiResponse(code = 100, message = "100 is the message"), 
      @ApiResponse(code = 200, message = "Successful List")})         
      @GetMapping                                                             
      public List listar() {
       return restaurants.findAll();
   }


Example  2:

@ApiModelProperty(notes = "Id of the restaurant")
@Id @GeneratedValue (strategy  = GenerationType.IDENTITY)               
private Integer id;
@ApiModelProperty(notes = "Name of the restaurant")                     
private String name;

Bio API

There are many APIs used in bioinformatics that uses swagger tool. Some of them:

  • http://rest.ensembl.org/
  • https://www.programmableweb.com/category/science/apis?category=20070&page=1
  • https://www.ncbi.nlm.nih.gov/home/develop/
  • https://biojava.org/
  • https://www.ebi.ac.uk/uniprot/japi/
  • http://www.ebi.ac.uk/pdbe/pdbe-rest-api
  • https://www.ebi.ac.uk/proteins/api/doc/#proteinsApi

Conclusion

It is a great tool to who want to develop some API or understand how it works. It an easy tool so go on and hands-on. If you want, there is the source code and a step-by-step video.

Referências

  • http://blog.caelum.com.br/modelando-apis-rest-com-swagger/
  • http://blog.caelum.com.br/documentando-uma-api-jax-rs-com-swagger/
  • http://www.matera.com/blog/post/swagger-como-gerar-uma-documentacao-interativa-para-api-rest
  • http://idratherbewriting.com/learnapidoc/pubapis_swagger.html