The Easiest and Quickest Way to Generate an OpenAPI Spec for an Existing Website

If you’re working on a project that involves building an API for an existing website, you’ll need an OpenAPI specification to describe the API. An OpenAPI spec is a document that describes the endpoints, request and response parameters, authentication requirements, and other details of the API. It can be a time-consuming task to create an OpenAPI spec from scratch, but there are tools available that can help you generate one quickly and easily.

In this blog post, we’ll show you how to generate an OpenAPI spec for an existing website using HTTP Archive (HAR) files, which are recordings of a web browser’s interactions with a website.

Step 1: Collect API Endpoints

Before you can generate an OpenAPI spec, you need to collect all the API endpoints for the website you’re working on. One way to do this is by using the Chrome browser’s built-in developer tools to monitor network traffic and save it as a .har file.

Here’s how to use Chrome to collect API endpoints, I’m going to use Bitbucket website for my demo

1. Open Chrome and navigate to the website for which you want to create an OpenAPI spec.
2. Open the Chrome developer tools by either clicking the three dots in the upper right corner of the browser window and selecting “More tools” > “Developer tools” or right-clicking anywhere on the page and selecting “Inspect” from the context menu.
3. In the developer tools window that appears, select the “Network” tab.
4. Select the “XHR” filter to display only the API requests.

5. Refresh the page to start capturing network traffic.

6. Perform the actions on the website that trigger the API calls you want to include in the spec.

7. In the network traffic log, locate the API requests and click on them to view their details.

8. Click the “Export” button at the top of the network traffic log and save the file as a .har file.

Save the .har file

Step 2: Generate an OpenAPI Spec with Tools

There are several tools available that can help you generate an OpenAPI spec from the .har file you created in Step 1. In this example, we’ll use APIGit, a Git platform for API development, to generate the spec.

Here’s how to use APIGit to generate an OpenAPI spec:

1. Go to https://app.apigit.com/ and sign up for a free account if you don’t already have one.
2. Once you’re logged in, create a new repository for your OpenAPI spec by clicking the “Create Repository” button.
3. Name your repository and give it a description.
4. Under the “API Specifications” tab, click the “add or upload spec” button and choose the .har file you created in Step 1.

upload .har in APIGit

5. Click the “Create” button and wait for APIGit to process the file.

6. Once the file is processed, you’ll see a visual representation of your API endpoints.

View and modify APIs in APIGit

Step 3: Repeat Step 1 to Collect More Actions

It’s difficult to collect all APIs for the website at once, so most likely you’ll need to repeat Step 1 for different use cases. For example, if you’re working with Bitbucket, you may have already collected the APIs for creating a repository and submitting a commit. Now you may want to collect the APIs for creating a branch, making a pull request, merging the pull request, and so on.

To collect APIs for these additional use cases, follow the same process as in Step 1. Open the Chrome developer tools, navigate to the relevant page on the website, perform the actions that trigger the API calls, and save the network traffic as a .har file.

Step 4: Import New .Har File to Generate APIs

As you work on your website, you may need to collect additional APIs or make changes to existing ones. To update your OpenAPI spec with these changes, you can import a new .har file into APIGit and generate the updated API description.

When importing a new .har file, you have two options for handling duplication:

1. Import the .har file into the existing spec: APIGit will automatically detect any duplicate APIs and only save one copy. To do this, navigate to the current API spec and click the “Edit” button to enter the API editing page. Then, click the “Import” button at the top and upload the new .har file.

Import new .har into an exisiting spec in APIGit

2. Import the .har file into a new spec: If you want to keep the original spec and compare it with the new one to see what has changed, you can create a new spec and use the diff function to compare the changes. To do this, follow the same steps as described in Step 1, but instead of importing the file into the existing spec, click the “add or upload spec” button to create a new spec. You can then use the diff view by clicking the “switch” button to compare the changes between the original and updated specs.

use diff function to compare changes

diff in APIGit

Step 5: Repeating Steps 3 and 4 Until All APIs are Collected

Collecting all the APIs for a website can be a time-consuming process, especially if the website has a lot of functionality. It may take several rounds of browsing the site and collecting .har files before you have all the necessary APIs for your OpenAPI spec. Here are the steps to repeat until you have collected all the APIs:

1. Repeat Step 1: Use Chrome Developer Tools to browse the website and collect .har files for additional use cases.
2. Repeat Step 2: Generate an updated OpenAPI spec using the new .har files. Remember to choose the appropriate option for handling duplication when importing the new .har file.
3. Review the updated spec and make any necessary edits to ensure accuracy and completeness.
4. Repeat Steps 1–3 as needed until you have collected all the necessary APIs for your website.

Step 6: Completing and enhancing your APIs

Once you have collected all the necessary APIs and generated your OpenAPI spec using APIGit or another tool, it’s time to review and enhance your API description.

A comprehensive API spec should include detailed descriptions of each API, request and response definitions, data validation, and other important details. With the autogenerated spec in hand, you can start to make edits and fill in any missing information.

APIGit offers an intuitive OpenAPI editor that can help you complete your APIs more quickly and easily. With the editor, you can easily add or edit tags, parameters, responses, and other details for each API. You can also validate your API definition to ensure that it complies with the OpenAPI specification.

In addition to completing the API definition, you can also enhance your APIs by adding documentation and examples to help other developers understand how to use your API. This can include detailed tutorials, code snippets, and other resources that make it easier for other developers to get started with your API.

By completing and enhancing your APIs, you can ensure that your API documentation is accurate, complete, and easy to use. This will help other developers to work more efficiently with your API and can ultimately lead to more adoption and success for your project.