API and Swagger

by Marius Crișan

1.1 Introduction

    Swagger is the largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

The specification creates the RESTful contract for your API, detailing all of its resources and operations in a human and machine readable format for easy development, discovery, and integration.

2.1 Developing APIs

   When creating APIs, Swagger tooling may be used to automatically generate an Open API document based on the code itself. This is informally called code-first or bottom-up API development. While the software code itself can accurately represent the Open API document, many API developers consider this to be an outdated technique as it embeds the API description in the source code of a project and is typically more difficult for non-developers to contribute to.

2.2 Interacting with APIs

Using the swagger-codegen project, end users generate client SDKs directly from the Open API document, reducing the need for human-generated client code. As of August, 2017, the swagger-codegen project supported over 50 different languages and formats for client SDK generation.

2.3 Documenting APIs

When described by an Open API document, Swagger open source tooling may be used to interact directly with the API through the Swagger UI. This project allows connections directly to live APIs through an interactive, HTML-based user interface. Requests can be made directly from the UI and the options explored by the user of the interface.

3.1 Basic Structure

The documentation needs to be in a JSON or YAML format and field names are case sensitive.
The documentation may consist of a single document or divided in multiple documents, in which case the $ref fields must be used in order to reference those parts. For each route we can describe the type of request, the parameters we need to send, and the response we expect to receive.

This will produce the following.

In the generated documentation file you can also try out the route and see exactly what you receive as a response.

3.2 Parameters

In OpenAPI 3.0, parameters are defined in the parameters section of an operation or path. To describe a parameter, you specify its name, location (in), data type (defined by either schema or content) and other attributes, such as description or required. We can use the following parameters types:
- Path parameters
- Query parameters
- Header parameters
- Cookie parameters

3.3 Request Bodies

Request bodies are typically used with “create” and “update” operations (POST, PUT, PATCH). For example, when creating a resource using POST or PUT, the request body usually contains the representation of the resource to be created.

OpenAPI 3.0 provides the requestBody keyword to describe request bodies.

Example of a request body:

3.4 Responses

An API specification needs to specify the responses for all API operations. Each operation must have at least one response defined, usually a successful response. A response is defined by its HTTP status code and the data returned in the response body and/or headers.
Example of a response:

4 Conclusion

There are a lot of benefits for using Swagger and the most important ones would be that it creates a documentation which is very easy to read, you can execute the routes to see exactly what you will receive and you have all the request/response details in a nice format. One disadvantage of using this tool is that you will have to write more documentation and it may make the controllers harder to read. Overall this tool is very helpful in making the end user know what you are offering and what to expect from the API.

Leave a Reply

Your email address will not be published. Required fields are marked *