by Farian Hadi Saputra, Analyst Programmer at Mitrais

Swagger

a. Swagger for API documentation

Good documentation is essential when developing APIs. A well-documented API will assist the user (ie: you the developer) to use it effectively and integrate the API into the codebase easily. When our users are able to learn our API easily and quickly, we can reduce the cost and time for supporting them. In addition, as the API owner, documentation will help your internal team to maintain and to update the API with minimum effort and risk of breakage. Swagger will help you to create well-structured API documentation.

Swagger can be integrated using most major programming language frameworks, such as JAVA, spring boot, NodeJS, loopback, etc. The endpoint documentation is autogenerated by detecting any existing endpoints on our system. As a developer, we just need to customize what we need to add or modify.

We can also develop swagger documentation manually, by just downloading swagger and swagger UI. It can be downloaded from here.

b. Swagger for Designing APIs

On many projects, the development team is separated into 2 “sides” which are backend side and frontend side. The backend team handles the business logic through the API endpoint, and the frontend team have the responsibility to create the user interface which will be accessed by the user directly. Using swagger documentation, as a team, we can define the API response and request. It is essentially an agreement or contract on how to communicate. By acting as a bridge for both sides they can both commence development in parallel.

We able to define parameters, request data, response data, response code, which fields are mandatory or optional, and other information. Therefore, by designing first using swagger, we are able to communicate and tell any stakeholder what input and output is required for each endpoint API.

When you are designing the API from scratch, you can do it using this in the cloud. On this site, we can create the design using code in YAML format, then it will be translated into a web format view. See the details on the following screenshot.

c. Swagger for “trying out” APIs

Swagger does not just provide documentation, it also allows the user to try the API. The user able to use the sample request data, add token if the API already has an authentication mechanism, then by just clicking the button try it out, they can see the result.

Newman

Integration Testing is also essential when developing APIs. By doing integration tests, we are able to ensure that each endpoint works as expected or not. Integration tests can be done through Postman.

Anyone working with API development will be familiar with this tool for testing single endpoints. Postman also has a feature to do several sequential tests in one execution process. We just need to define the test itself on the Collections tab, then run it using the Runner tab.

That is how we create an integration test. The question is… if we are going to run this automatically, how we do that? The solution is using Newman.

Newman is able to execute Postman collection runner via the command line. By this method, we can integrate it using our continuous integration server such as Jenkins or TeamCity.

Then we will get the result as the following example

The report could be generated in several formats such as HTML and json. For the complete documentation, please check this Newman documentation link.

Conclusion

By including Swagger and Newman into your development toolset, and maximizing all of the features that they offer you can radically improve communication between development teams and improve quality and maintainability.