Learn how to design, document, and build APIs faster.
This guide was originally created and published by Tom Johnson on his website, I’d Rather Be Writing, and you can find the original content here.
In this tutorial, we will walk through using Stoplight for modeling an API. We will create a valid OpenAPI description, using the OpenWeatherMap as the sample API. With Stoplight, you can design, document, and build APIs faster. For a higher-level introduction to the OpenAPI specification, see Introduction to the OpenAPI specification.
Before we get started, let’s address an initial question about the approach we’re taking. When creating your OpenAPI specification document, why should you use a visual/GUI editor, which hides the code (unless you toggle the Code View open) instead of coding every detail of the spec by hand?
All approaches have their merits. But if you don’t work with the OpenAPI specification enough to remember all the fields and syntax for each property, or if you’re learning it for the first time, trying to get the syntax valid in the raw code can be challenging. Coding by hand leads to many errors and forces you to spend a lot of time troubleshooting invalid syntax.
Using an editor helps you avoid these errors and focus instead on the content. The less time you spend fiddling with syntax and more time working on content, the better the outcome of the API design and the documentation. Stoplight lets you switch into the code view to work in that mode when you want, and switch back into the visual view when you want. This gives you the best of both worlds.
This tutorial should take about 30 minutes to an hour. No special technical knowledge is required.
In this tutorial, we’ll use sample information from the OpenWeatherMap API (more specifically, the Current weather data endpoint), which is the same API we’ve been using in other tutorials, such as the OpenAPI tutorial.
Here’s the documentation output that you’ll build in this tutorial:
Stoplight provides a variety of options for working with projects — you can create a Stoplight project from scratch or connect to a Git repository and commit and publish your changes using a Git workflow. In this tutorial, you’ll take the simplest path: using the web editor and creating a Stoplight project. But recognize that you have more options for how you approach projects.
The Stoplight editor opens. The left pane says, “You do not have any APIs or models.”
Stoplight creates an OpenAPI (OAS) specification file called openweathermap.yml and loads it:
The sample code includes some content for some fictitious user endpoints called /users/{userid} and /user.
You could simply paste in a valid OpenAPI spec into the Code view, and it would populate the Form view. But presumably you don’t already have an OpenAPI spec to paste into the code — this is why you’re using the editor, to build out the specification document.
The ability to switch views between Form, Code, and Preview gives you a lot of authoring power.
In this section, you will populate the fields in the API Overview section, which include the version, name, description, security, contact, license, and other general details. For this tutorial, We've prepared sample information for you to easily insert into the Stoplight Editor. (Note: In the sample information in the blue expandable sections, titles are in [brackets] for fields that don't have names.)
To populate the API overview:
Note: This sample Swagger file covers the current endpoint only from the OpenWeatherMap API.
Note: All parameters are optional, but you must select at least one parameter. Calling the API by city ID (using the id parameter) will provide the most precise location results.
Note: The Markdown source formatting in the sample text is intentional. When you copy and paste in the source, Stoplight will convert the Markdown into HTML when displaying the published page. Also note that Stoplight allows you to use Stoplight-flavored Markdown, which allows all the same tags as CommonMark but also includes some special tags for callouts, alerts, and other formatting.
When finished, the form should look as follows:
Tip: If you are seeing the Preview window side-by-side with the Form or Code view, you can make your browser window smaller so you can view the Preview window in full size.
Now enter the path and parameter information:
By default Stoplight creates a GET operation for the weather endpoint. In our case, this works out great because this endpoint has a GET endpoint. But if not, you could just click the other operations available to create details for those operations.
You can remove the default /users/{userid} and /user and endpoints. Right-click each endpoint and select Delete Path.
This tag will group the endpoints in the sidebar by this tag into a collapsed section called “Weather endpoints.” This is how you build navigation hierarchy for your endpoints. You won’t see this grouping until you publish your API, though. Here’s a screenshot of what that grouping will look like:
When you’re finished entering the parameters, Stoplight should look like this:
You don’t need to add security for this endpoint because you already configured global security in the previous section. However, if this endpoint had a unique security method, you could override the global security here by clicking the + Security button.
The OpenAPI spec allows you to re-use parameters by storing the information in the components property. In the Stoplight editor, you reuse parameters by entering the parameter information in the Parameters section in the sidebar. (In the code behind the scenes, this is stored in components.)
To understand how this works, let’s re-use one of the query parameters.
To re-use a parameter:
You don’t need to do anything in the code here — this is just to point out what changed behind the scenes. You can use this same technique to re-use other parameters as well as other types of content, such as responses.
This endpoint in the OpenWeatherMap API doesn’t have any path, header, or body parameters, so you can skip those elements.
As a final step for this endpoint, you need to enter the response information. The response includes not only an example response, but also the schema describing the response. The schema describes all possible values in the response, their data types, and whether the values are required.
To enter the response information in Stoplight:
Here you’ll experience one of the coolest features in the Stoplight editor. The editor will automatically build out the response schema from a sample JSON response.
For the description and examples, copy over the information in the gray section below.
You’ve finished creating your OpenAPI spec, so let’s preview, test, and publish test the documentation:
The Bundled References will resolve any $ref code and place them in the components section so there’s no duplication. The Original will export any $ref code, but not resolve them. The option you choose depends on what’s supported in the editor you’re bringing it to.
Tip: You can view the finished OpenWeatherMap API documentation from this tutorial on Stoplight here. If you got stuck in the tutorial somewhere along the way, you can click Export to download the OpenAPI description and paste it into your code.
We hope you found this guide helpful, and for similar content visit I’d Rather Be Writing or check out our other Stoplight guides. You can get started for free in Stoplight by clicking here.
Contents