The OpenAPI Initiative (OAI) has become the de facto standard to specify what an API can do. The API community as a whole has embraced the standard, and tooling around OpenAPI, especially Swagger, has never been better, with ways to document, implement, and test APIs that adhere to the standard. This is an awesome thing for the API community. Instead of taking precious time to create homegrown standards and ways of creating, testing, and monitoring APIs, API providers can follow the specification and avoid much of the standard work to build an API, and focus on innovating by what their APIs can do. Here’s more about why you should create a definition. Below, find instructions for how to create an API definition if your API is already built and working. If you’re designing your API and don’t yet have the API built, check out our Getting Started with SwaggerHub guide.

1. Go to Swagger Inspector

You’ll need to login or sign up for a free account to proceed with the next steps.

2. Make calls to your API

  • Make a call to every endpoint, filling in your URI, method (GET/POST/etc), and any parameters, headers, and authentication details needed for the API.
  • You’ll see your API requests fill into your history to the right of the request pane after you send requests.
  • If you have more than 20 endpoints (the limit), we recommend creating an API Definition for sets of API calls that are related. We regularly see API Definitions that are thousands of lines long - ask yourself what API calls are likely to be used together, and organize accordingly instead of creating a huge file.

Requests in Swagger Inspector

3. Select requests in the History and create API definition

In the History panel, select the check boxes next to the API calls you want to include in the API definition. It makes sense to choose only API calls made to the same API (calls that share a base URI).

After you have selected the requests, click Create API Definition. Swagger Inspector can create OpenAPI 3.0 and OpenAPI 2.0 (aka Swagger 2.0) definitions - you can choose the desired version from the dropdown.

Create an OpenAPI definition from the selected requests

4. Follow the prompts to go to SwaggerHub

Proceed to SwaggerHub to see the generated OpenAPI definition

5. Name your API

The API name is a general name for the API and can be internal. If you already have a version, fill it in. Otherwise, we recommend leaving the default for unpublished APIs (0.0.1) or using 1.0.0 for brand new APIs. Versions are usually denoted major.minor.veryMinor.

API name and version

6. Your definition is there!

You’ll edit on the left pane - the text editor, and see changes in the right pane - the “UI” portion. You can make any changes you’d like to your definition file, which will be viewed as YAML. For example, you probably want to add your API title (that could be the same as the API name). You can also add information about logic that might not be obvious, like point out any values that are mutually exclusive.

API definition in SwaggerHub

Create a Swagger account now to get access to SwaggerHub and Swagger Inspector.