Search results

Activity: Use Stoplight to edit your OpenAPI spec

In previous activities, you created your own OpenAPI specification document and also created a Swagger UI display with that specification document. In this example, you’ll make some modifications to your specification document using Stoplight, a visual editor.

If you landed on this activity before learning about Stoplight, read Stoplight — visual modeling tools for creating your OpenAPI spec first.

Download and populate Stoplight with an OpenAPI specification

In this activity, you’ll download and explore Stoplight. To speed things up, you’ll start with an OpenAPI definition that you paste into the Stoplight editor, and then you’ll make some modifications to it using Stoplight’s visual modeling tools.

You can use Stoplight in the browser or as a web app. For simplicity, we’ll use the browser version. For the OpenAPI spec that you paste in, use the custom specification you created in an earlier activity with the spec. However, because Stoplight supports only the 2.0 version of the spec (as do most tools currently), you’ll need to convert your 3.0 version to 2.0 using the API Transformer (a nifty converter tool from APIMATIC). Alternatively, you can use the 2.0 version of the Sunrise and Sunset OpenAPI spec that I’ve already converted, or the 2.0 version of the OpenWeather Map API that I’ve already converted.

To download and populate Stoplight with an existing OpenAPI spec:

  1. Go to
  2. Click Login in the upper-right corner and log in through your GitHub account.
  3. Click New Project.
  4. Type a Project name (e.g., Sunrise and Sunset API), a Project path (e.g., the default path), and a Summary (e.g., “Documentation for Sunrise and Sunset API”). Leave the visibility as Public and click Create Project.
  5. In the left pane, click the Files icon to expand the left pane, and then click under Modeling, click main.oas2.
  6. At the top of the screen, click </> Code to switch into the code view.
  7. In the main content area, delete any existing code shown, and then paste in a 2.0 version of your Swagger spec. (See the introductory text above for a sample spec to use.)
  8. Click Save and then Confirm.
  9. Click the Design button at the top to switch back to the visual view.

Explore Stoplight and make some edits

Now that you have some data populated in Stoplight, let’s explore Stoplight a bit more by expanding various sections and making some modifications.

  1. In the side pane, expand PATHS and then expand your endpoint. It should look something like this:

  2. In the main content area, the API content is grouped in several sections: Basics, Request, and Responses. Explore each of these sections by expanding them and viewing the content.
  3. Expand the Requests section, then expand [#] Query Parameters. Make an edit to one of your query parameter descriptions by clicking the button.
  4. Expand the Responses section, and for the 200 response, select the Raw Schema tab and delete the existing content. It will leave {} there, which is good.
  5. Switch to the Editor tab, click Generate from JSON and paste in the following JSON response from the OpenWeatherMap weather endpoint.

      "coord": {
        "lon": -121.96,
        "lat": 37.35
      "weather": [
          "id": 721,
          "main": "Haze",
          "description": "haze",
          "icon": "50n"
      "base": "stations",
      "main": {
        "temp": 67.42,
        "pressure": 1012,
        "humidity": 40,
        "temp_min": 55.4,
        "temp_max": 77
      "visibility": 16093,
      "wind": {
        "speed": 12.75,
        "deg": 300,
        "gust": 8.7
      "clouds": {
        "all": 75
      "dt": 1524448800,
      "sys": {
        "type": 1,
        "id": 479,
        "message": 0.0043,
        "country": "US",
        "sunrise": 1524489736,
        "sunset": 1524538230
      "id": 420006397,
      "name": "Santa Clara",
      "cod": 200
  6. Then click Generate!.

    This video shows the process of auto-generating JSON. (Instead of starting with the above sample JSON, the video makes request in Postman and then copies the response from there — but the idea should be clear.)

    Stoplight's visual modeling tools let you automatically create the correct JSON schema definition from a block of JSON that you paste in.
  7. Switch between the Code and Design views by clicking the corresponding buttons at the top. Make some edits in the code and then switch to the Design view to see the edits reflected. The following video shows this process:

    When you switch to the code view, the editor automatically goes to the part of the spec you were creating in the visual editor and highlights it. When you switch back, the visual UI updates with any changes you made in the code. Switching between modes is seamless and easy.

Note that Stoplight is one of the sponsors of my site.

71% Complete

71/109 pages complete. Only 38 more pages to go...


Would you like to help encourage more content development and updates? If so, click the Donate button below to donate $10 through Paypal.

Get new posts delivered straight to your inbox.

Subscriber count: 4,285