How to use OpenAPI in testing

What is OpenAPI?

OpenAPI (earlier known as Swagger) is considered to be a standard for describing API interfaces and using them in testing. OpenAPI allows you to describe all API capabilities and limitations (available operations, parameters, response formats). The description is used to automate API tests and to ensure mutual compatibility between different tools and services.

API can be described in YAML or JSON formats. The general structure of OpenAPI in YAML format is as follows:

Correct indentation is important for the YAML format, as it affects the document structure. YAML also uses dashes to describe a list of values ​​(such as a list of servers) and colons to describe keys and their values.

In JSON format, this code looks like this:

The basic structure consists of 8 objects:

• OpenAPI version number used in the documentation;
• general information about  API (name, description, version) - info object;
• the list of servers where you can run API (in our case, shown in the screenshot above as an example), is a single one - https://api.example.com/v1);
• description of paths to API resources and methods that can be used to interact with these resources. In our case, there is one path to the /users resource that can be used to get a list of users (GET method) and create a new user (POST method). Each method has a description that includes a request header (summary), a list of responses (responses), and information on how to interact with the request body (requestBody);
• components, such as schemes, parameters of requests, responses, etc. In our example, there are two schemes: User and NewUser. The User scheme contains three properties – ID, name, and email, each of which has its own data type. These schemes can be reused in different places in the specification, instead of having to copy their descriptions each time.

There are also such things as security, tags, and externalDocs, but in our example, they are missing.

API documentation is an immensely important element for developing, testing and using an API. Let's see why:

1. The documentation helps you understand how the API works and how to interact with it. It provides information about available endpoints, query parameters, data formats, error codes, and more. This reduces the time required to develop and test the software that uses the API.
2. Documentation reduces the number of errors when interacting with the API. Users can check the correctness of API requests and responses, which reduces the number of errors and speeds up development.
3. Documentation makes the API more accessible. Thanks to well-written documentation, developers can quickly integrate it into their projects, which increases the number of users.
4. The documentation helps maintain compatibility between versions of the API. If the documentation specifies which fields and parameters can be used in the API, changes in new versions will be less likely and easier to control.

The main functional features of OpenAPI include:

1. Description of API methods: OpenAPI allows you to describe the methods supported by APIs (GET, POST, PUT, DELETE, etc.), including the types of requests and responses expected from APIs.
2. API documentation: Based on the API description, OpenAPI has a feature to automatically generate documentation that describes the methods used and the types of requests and responses.
3. Validation check: OpenAPI allows validating API requests, which helps prevent errors and provides greater system stability.
4. Support for different formats: allows you to describe APIs in JSON and YAML formats.
5. Generation of client libraries: automatic generation of client libraries for various programming languages ​​based on the API specification.
6. API testing support: OpenAPI allows the automatic generation of test requests for API, which helps to verify its functionality.
7. Automatic documentation support: automatic creation of API documentation based on the specification.
8. Compatibility with other tools: OpenAPI integrates with many other tools, such as Swagger UI, which allows interaction with APIs in the browser, as well as with various automated testing and CI/CD frameworks.

These functionalities make OpenAPI a powerful tool for API description and development. 

In testing, OpenAPI can be used to automatically generate test scripts according to the API description in the specification. Such test scripts can verify that the API is working correctly and conforms to the specification. Also, OpenAPI can be used for the automated generation of API documentation, which will be useful for developers working with API, as well as testers who can use the documentation to understand how API should work.

The best way to learn OpenAPI is through a hands-on approach. Certain tools allow you to edit OpenAPI specifications and then generate API documentation. Swagger Editor or Swagger UI is often used for rendering convenience.

SwaggerUI is a tool that parses API definitions to generate documentation. SwaggerUI has a browser-based editor (shown below). If you want to experiment with the SwaggerUI editor, you can do it here: https://editor.swagger.io/

With the help of the editor, you can:

1. Convert the specification from JSON to YAML and from YAML to JSON.
2. Convert OpenAPI 2.0 to 3.0 (Edit->Convert to OpenAPI 3) in case of upgrade.
3. Generate a Server based on a specification or a Client based on a specification for application development or testing.
4. Send a test request to the endpoint to check its operation.

The Swagger Petstore specification is an example of the OpenAPI document.

The left sidebar shows the OpenAPI specification in YAML format. Whenever you make changes to a specification, those changes generate new documentation in the right sidebar. The right sidebar is a Swagger document built directly from the OpenAPI specification (left sidebar). For example, changing the path description causes the Swagger document to be updated with the new changes.

If you look at the OpenAPI Swagger specification on the left, you can see all the sections described in this blog article, including openapi, info, servers, paths, components, tags, and more. After familiarizing yourself with Swagger Petstore, it's possible to insert another API's specification into the Swagger Editor to see how its information is displayed in SwaggerUI.

Swagger throws an error if you deviate from the OpenAPI structure or if something is entered incorrectly. Swagger's error handling reinforces the concept that the OpenAPI format must be followed in order to display the documentation correctly.

You can extend the API in the editor to view the details. In our example, this is GET /pet/{petId}

For the operation GET /pet/{petId} you can see that:

• responses: with the value «200» for a successful operation;
• media type app/json;
• data for each element is returned in an array.

Also, you can send a request using the «Try it out» button to test the API.

OpenAPI specifications and the Swagger Editor/Swagger tools are essential elements for API testing. The article discusses only a few examples of the use of these tools, but OpenAPI provides flexible capabilities that allow you to significantly automate routine testing processes and make life easier for testers.