Step 2: The info object (OpenAPI tutorial)
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: OpenWeatherMap API description: 'Get current weather, daily forecast for 16 days, and 3-hourly forecast 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
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:
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.
60/96 pages complete. Only 36 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.