Search results

Step 2: The info object (OpenAPI tutorial)

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,300+ subscribers

I'm giving an API documentation workshop in Los Angeles, California, on January 23, 2020. You can view details on EventBrite here.

Input needed: I'm currently conducting a survey about trends in developer documentation for 2020. If you write docs for developers, please take this survey. (You can view the ongoing results viewed here.)

The info object contains basic information about your API, including the title, a description, version, link to the license, link to the terms of service, and contact information. Many of the properties are optional.

Swagger

Here’s an example of the info object and its properties. (The openapi object and the empty paths object are commented out to maintain the focus on the info object.)

# openapi: 3.0.2
info:
  title: "OpenWeatherMap API"
  description: "Get the current weather, daily forecast for 16 days, and a three-hour-interval forecast for 5 days for your city. Helpful stats, graphics, and this day in history charts are available for your reference. Interactive maps show precipitation, clouds, pressure, wind around your location stations. Data is available in JSON, XML, or HTML format. **Note**: This sample Swagger file covers the `current` endpoint only from the OpenWeatherMap API. <br/><br/> **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."
  version: "2.5"
  termsOfService: "https://openweathermap.org/terms"
  contact:
    name: "OpenWeatherMap API"
    url: "https://openweathermap.org/api"
    email: "[email protected]"
  license:
    name: "CC Attribution-ShareAlike 4.0 (CC BY-SA 4.0)"
    url: "https://openweathermap.org/price"
# paths: {}

In any description property, you can use CommonMark Markdown, which is much more precise, unambiguous, and robust than the original Markdown. For example, CommonMark markdown offers some backslash escapes, and it specifies exactly how many spaces you need in lists and other punctuation. You can also break to new lines with \n and escape problematic characters like quotation marks or colons with a backslash.

As you write content in description properties, note that colons are problematic in YAML because they signify new levels. Either enclose the description value in quotation marks or escape colons with a backslash. (If you enclose the values in quotation marks, syntax highlighters in text editors can display better color coding between the properties and values.)

To update the spec file in Swagger Editor:

  1. Paste the above code containing the info object into the Swagger Editor.
  2. Uncomment the openapi and paths objects (remove the “#”). The display looks as follows:

    openapi, info, and empty paths object in Swagger Editor
    openapi, info, and empty paths object in Swagger Editor

    In the Swagger UI display, the info object’s information appears below the title.

In the description property, in addition to describing your overall API, you might want to provide some basic instructions to users on how to use Swagger UI. If there’s a test account they should use, you can provide the information they need in this space.

Stoplight Studio

Now let’s look at how to add this same information using Stoplight Studio.

  1. Below the title, in the description area, paste in the description from the code sample above.

    Note that Stoplight allows you to use Stoplight flavored Markdown. This Markdown version allows all the same tags as Commonmark but also includes some special tags for callouts, alerts, and other formatting.

  2. In the Contact section, paste in the contact information from the code sample above.
  3. In the License section, paste in the license information from the code sample above.
  4. Preview the doc by clicking Publish and then sliding the Show Preview slider.

    Previewing the docs
    Previewing the docs
  5. To exit the preview, move the Show Preview slider off and click the Publish button to hide the menu.
67% Complete

67/151 pages complete. Only 84 more pages to go.