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).
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.
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 :
- Add an endpoint name/title (1)
- Select the operation (2)
- 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.
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.
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.
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).
Finally, click on Save. Your OAS is now generated, and the API is ready to use inside a Spell!