In many practical tasks, it’s necessary to quickly and efficiently build an API for information systems. This applies to both monolithic systems and provides a custom API in the form of REST for communicating with third-party applications, as well as microservice architectures that organize a modular structure within an application.

When building software interfaces based on REST API, it’s necessary to solve several problems in these areas:

• organize the design of API calls and the corresponding input/output data;
• maintain documentation of API calls;
• quickly update documentation when changes are made to the system;
• if possible, automate the generation of files for the server and client parts for certain programming languages ​​and frameworks.

In principle, the OpenAPI specification and the corresponding tools from Swagger cope with these and other tasks at a good level. Generally speaking, this OpenAPI standard is considered for API development and the corresponding set of tools.

Why APIs are an important part of an information system

First, let’s look at what an API is in real projects and the properties it has:

API category for web services:

• Web services APIs send and receive messages over HTTP using JSON to transmit the request and response.
• Web services APIs are independent of the programming language or framework.

Native Libraries or Internal Microservices APIs:

• Native library APIs include adding code directly to a library or microservice to provide the desired functionality.
• the concrete implementation of the native library API partly depends on the language, but it can be successfully implemented in other languages as well.

There is a lot of attention to be paid to REST API design and documentation. REST API documentation is important because REST follows the architectural style, but not the exact protocol standard, for any particular system.

To understand the importance of documentation for REST APIs, it’s helpful to compare REST and SOAP. REST APIs are slightly different from SOAP APIs. SOAP APIs provide a special message format for sending requests and receiving responses. Using the XML message format, SOAP has a Web Service Description Language (WSDL) file that describes how to interact with a specific API.

REST APIs do not follow the standard message format. REST is more of an architectural style, a set of recommended practices for sending requests and receiving responses. To understand the format of REST API requests and responses, there is no way to look at the SOAP message specifications or examine the WSDL file. To obtain comprehensive information about a specific call, you need to refer to the documentation for a specific REST API.

All APIs are unique and fulfill their intended purpose. There is no single way of doing programming interface development, so this flexibility and variety require accurate and straightforward documentation. Each specific REST API is unique, thus, designing or documenting a programming interface requires both highly skilled developers and well-chosen development and documentation tools.

API Specification Industry Standard

REST (Representational State Transfer) is a web service that allows you to send requests to resources via URL paths. This specifies the operation to be performed using the specified path (for example, GET, CREATE, DELETE). As with other web service APIs, requests and responses are sent over HTTP over the Internet, and the servers receiving the requests are independent of the requested language. Replies are usually returned in JSON or XML format. REST APIs have many different paths (endpoints) with different parameters that can be customized to determine the desired results.

As described in the OpenAPI Specification page "The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases."

OpenAPI is a specification of machine-readable files with interfaces for describing, creating, using, and visualizing REST web services. There are various tools that can generate code, documentation, and tests on the file with the description of the interface, the main of which is Swagger. The OpenAPI (OAS) specification is overseen by the Open API Initiative, a Linux Foundation project.

In a nutshell, the API Specification is a file for describing API calls, compiled in JSON or YAML format in a certain notation, which describes the endpoint, input, output information.

Here is a very clear and easy-to-understand example that describes calling API at a specific address http://myapi.mydomain/v1 and returning data on a GET request.

openapi: "3.0.0"
info:
  version: 1.0.0
  title: My API
servers:
  - url: http://myapi.mydomain/v1
paths:
  /data:
    get:
      summary: Get data
      responses:
        '201':
          description: Data response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Data"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Data:
      type: string
Code language: PHP (php)

It becomes clear that it is possible to write a file manually, but it can be done much faster and more efficiently using specialized tools. The use of software for working with OpenAPI becomes especially important when developing APIs with a large number of calls and various data.

For fast and high-quality design, development, and documentation of APIs, Swagger and OpenAPI tools are very often used in real projects.

Installing Swager-UI and Swagger Editor

The two main API development and documentation Swagger tools can be easily installed in many ways.

There are many variants to install Swagger-UI, and the quickest and most effective for different platforms is using docker containers.

To install docker, you can use the installation package for your operating system as detailed in docker.com

Then, to install the Swagger-UI, you simply type in console:

docker pull swaggerapi/swagger-ui
docker run -p 80:8080 swaggerapi/swagger-ui

To install the Swagger-editor, you can type the similar commands:

docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor

Then, type in your browser localhost:80 to access the Swagger-editor

Then, type in your browser localhost:80 to access the Swagger-editor

Documenting API with Swagger

What tasks does the OpenAPI standard set for documenting method calls?

• Decide on the request URL
• Specify HTTPS method to call (GET, POST, PUT, DELETE)
• Describe input
• Describe the output
• Specify error codes and error description attributes

For example, when you launch the Swagger Editor, you can edit your API description file. From a standard example, we can take the following description of the POST method for our object in the API:

paths:
  /pet:
    post:
      tags:
        - 'pet'
      summary: 'Add a new pet to the store'
      description: ''
      operationId: 'addPet'
      consumes:
        - 'application/json'
        - 'application/xml'
      produces:
        - 'application/xml'
        - 'application/json'
      parameters:
        - in: 'body'
          name: 'body'
          description: 'Pet object that needs to be added to the store'
          required: true
          schema:
            $ref: '#/definitions/Pet'
      responses:
        '405':
          description: 'Invalid input'
      security:
        - petstore_auth:
            - 'write:pets'
            - 'read:pets'

Code language: PHP (php)

Then, the following information will be displayed in the Swagger Editor window:

Now, let's take a look at one of the most interesting features of the Swagger Editor in the Generate Server menu. In the figure below, you can see how many platforms and frameworks you can get working code for your API.

In the Generate Client tab, you can start the code generation for the client side of this API call.

In the Generate Client tab, you can start the code generation for the client side of this API call.

Also, OpenAPI 3.0 enables describing APIs authentication and authorization schemes using the following: HTTP authentication schemes (Basic, Bearer, RFC 7235 and HTTP Authentication Scheme Registry), API keys in headers, query string or cookies, OAuth 2, OpenID Connect Discovery.

It is necessary to mention different libraries for supporting OpenAPI for different languages, for instance, Springfox for Java.

Swagger tools for API

There are many Swagger tools to operate with OpenAPI standard:

• Swagger Hub - Cloud solution for accelerating API delivery and quality through standards and collaboration, built on OpenAPI.
• Swagger Editor - API editor for designing APIs with the OpenAPI Specification.
• Swagger UI - Visualize OpenAPI Specification definitions in an interactive UI.
• Swagger Codegen - Generate server stubs and client SDKs from OpenAPI Specification definitions.
• Swagger Inspector - Test and document APIs without testing your patience.
• AlertSite - Monitoring Public & Private APIs with your Swagger Spec or OAS File.

Based on these solutions and tools, you can build high-quality, well-documented and tested APIs. These tools allow you to solve (almost) all tasks during design, implementation, testing, and supporting large and complex API for any size of your project.

Conclusion

Are OpenAPI and Swagger worth it? Without a doubt, the answer is yes.

With minimal costs to master the OpenAPI description standard and tools, you will get a lot of positive results:

• facilitating work with the design of the API
• Improving documentation for your API
• building tests based on your API specification
• generating code for the client and for the server based on the specification
• improving other developers' understanding of your API
• Visualizing and schematic representation of your API

Svitla Systems developers have extensive experience in operating OpenAPI standards, as well as Swagger development and documentation tools.

You can turn to our architects and systems analysts for help in the development of APIs and their implementation.

If you doubt whether to use Swagger and similar tools in your project, we can confidently say that it is worth spending time on these technologies in order to get a much better result later and save the budget and time on catching errors in various calls of your API.