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.

3) Place a check next to each API call you made

Once you place a check next to any request, the CREATE API DEFINITION, DELETE, and ADD TO COLLECTION options will become available. It makes sense to choose only API calls made to the same API (calls that share a base URI).

4) Select CREATE API DEFINITION

5) Follow the prompts to go to SwaggerHub

6) 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.

7) 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 JSON. For instance, you probably want to add your API Title (that could be the same as the API name). You could also add information about logic that might not be obvious, like point out any values that are mutually exclusive. Create a Swagger account now to get access to SwaggerHub and Swagger Inspector.