Quick 'n Easy API Spec Generation

‍

Amit Dubey

April 18, 2022 · 3 min read

‍

Problem Statement

APIs are used practically every day by developers. This involves not just using them but also integrating, reviewing, and doing research. While publishing and updating documentation may be time-consuming, APIs with no documentation can rapidly become a roadblock in a team’s productivity, limiting the team’s ability to grow, outsource, or disperse globally. Most organizations lack standard documentation for their APIs, which might cause more trouble than not having it.

The OpenAPI Specification (OAS) is a standard that defines programming language-independent interface descriptions for HTTP-based APIs. This enables both users and computers to understand the capabilities of a service without any source code or documentation. A user can interact with the API using OpenAPI specs with minimal knowledge of the service.

This is what completely ridiculous API (crAPI) OpenAPI specs looks like.

Why do we need OpenAPI Specifications?

1. The OAS is backed by industry leaders, representing strong awareness and mindshare in the industry.
2. OAS is a popular open-source framework to create and define RESTful APIs.
3. Easy to implement and wide range of integrated workflows.

But what if, your application doesn’t have OpenAPI specs? Can you create one?

The short answer is, YES!

We will generate a HAR file from the browser’s traffic and then convert that HAR to OpenAPI specifications using an open-source tool.

What is a HAR file?

The HTTP Archive Format (HAR) is a JSON-formatted file that is used to trace all web requests made by a browser to a web application. We can export the logs into HAR format which can be then analyzed through the free HAR analyzer available.

Read more...

To create these specifications for your application’s API you just need to follow the following steps-

‍

For demonstration purposes, we will use crAPI.

1. Use Firefox to navigate through your application.
2. Go to browser’s “Inspect-element” pressing F12 then click on the “Network” tab.

3. Now use the domain: filter and select “XHR” as an additional filter.

4. This will remove all of the noise from the network logs, leaving just API requests from your domain.

5. Now navigate the application using a valid set of credentials and data. This is done to ensure that all of the application’s API requests are covered.

6. After that, we can export our API to HAR format. Right-click on Network logs and choose “Save all as HAR.”

7. Here we will use an open-source tool called Avantation to generate specifications from the HAR file.

8. To install Avantation, simply use npm install -g avantation

9. Once it is installed and running, run avantation

10.This will generate an openapi.yml file, which is actually an OpenAPI specification for your application’s API.

11. We can now access and view our API specification file in Swagger-editor.

Using this technique we can generate API specifications for our application and use them to scan with LEVO, an intelligent API security testing tool.

Sign-up for free today.

Do let us know if you need any help with generating your own API specs and using them with Levo. We’ll be happy to help.

‍

Best Regards,

Amit

‍