OpenAPI tutorial step 2: The info object

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.

Sample info object

Here’s an example:

info:
  title: Weather API from Mashape
  description: "This is a sample spec that describes a Mashape Weather API as an example to demonstrate features in the Swagger-2.0 specification. This output is part of the <a href=\"http://idratherbewriting.com/learnapidoc\">Documenting REST API course</a> on my site. The Weather API displays forecast data by latitude and longitude. It's a simple weather API, but the data comes from Yahoo Weather Service. The weatherdata endpoint delivers the most robust package of information of the endpoints here.\n\nTo explore the API, you'll need an API key. You can sign up for an API through Mashape, or you can just use this one\: `EF3g83pKnzmshgoksF83V6JB6QyTp1cGrrdjsnczTkkYgYrp8p`. For the latitude and longitude parameters, you can get this information from the URL of a location on Google Maps. For example, for Santa Clara, California, use the following\:\n* **lat**: `37.3708698`\n* **lng**: `-122.037593` \n"
  version: "1.0"
  termsOfService: https://konghq.com/terms/
  contact:
    name: fyhao
    url: https://market.mashape.com/fyhao
    email: [email protected]
  license:
    name: Limited license
    url: https://konghq.com/terms/

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 escape colons with a backslash or enclose the description value in quotation marks.

Appearance in Swagger UI

In the Swagger UI display, the info object’s information appears at the top:

In the description property, 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.

Get new posts delivered straight to your inbox.

Subscriber count: 4,285