Skip to main content

Build OAS with API Builder

No need to spend hours to look for (or to create) an OpenAPI specification (OAS) file for your targeted API.

Our API Builder lets you build an OAS from scratch with no special technical knowledge.

In this tutorial, we’ll use sample information from the OpenWeatherMap API (more specifically, the Current weather data endpoint) to show you the process step-by-step.

Step 1: Enter the base path URL

The first step is to add the base path URL of your API. The base path URL is the part of the URL that appears before the endpoint.

For our use case, the base path URL is https://api.openweathermap.org/data/2.5 and the /weather endpoint refers to https://api.openweathermap.org/data/2.5/weather.

Once you've typed in the URL (1), we'll check its accessibility and give you some insights depending on the response code we received from the ping (2).

Add the base path URL

Step 2: Set up authentication

Next, you have to set up the API protection by choosing one of the following security scheme:

  • No authentication (1)
  • HTTP authentication schemes using the Authorization header, such as Basic authentication (2) and Bearer authentication (4)
  • API key (3)
  • OAuth 2 (5)

Please note that the security scheme will be attached globally to the OAS, and thus affect all endpoints.

Then, fill in the required information attached to the security scheme you selected. We’ll use the API key approach, since this is what the OpenWeatherMap API uses.

Set up authentication

Step 3: Enter the endpoint information and parameters

The endpoint contains the meat of your API information. It's appended to the base path (created in step 1) to construct the full URL.

You have to provide :

  1. Add an endpoint name/title (1)
  2. Select the operation (2)
  3. Add the endpoint URL (3)

For the weather endpoint in the OpenWeatherMap API, there is just one path (/weather) and one operation (get) for that path.

Add basic endpoint information

If your endpoint URL contains path parameters (for example weather/{country}/{city}), we'll parse the URL to extract each parameter. Then, you'll be able to add a description and select a value type for each of those.

Add endpoint path parameters information

Then, you can set up the parameters or the request body accepted by the endpoint. Each parameter has a name, value type and a description.

  • Header parameters (1): These parameters are featured in the request header and are usually related to authorization (X-MyHeader: Value)
  • Query parameters (2): These are separated from the hierarchy parameters by a question mark (/weather?lat=123456789). It makes no difference what order the query string parameters are in.

You can also add a request body (3) object that you'll be able to configure inside your Spell.

Add endpoint parameters information

Please note that we don't provide a way to add the response information yet.

Step 4: Enter the API overview information

In this final step, we ask you to provide high-level and basic information about your API such as the name, the provider, a description, one (or more) category(ies) and a logo URL (not required).

Add basic API details

Finally, click on Save. Your OAS is now generated, and the API is ready to use inside a Spell!