A documentation exercise of the OpenWeatherMap.org API.
The Swagger Editor can be found here. The Swagger Editor provides a split screen view where on the left you can write your code, and on the right a Swagger UI display forms in realtime.
The openapi object is the root-level property of the specification document. The latest version is "3.0.2".
The info object and its properties contains any important information about the API. The info object may indlude a title, description, contact information, license version, and/or terms of service. Many of the info object properties are optional. In this tutorial the API documentation is written in YAML. YAML indentation requires two spaces per level of identation. Tabs will not fit the formatting style. Text in the info object MUST be surrounded by quotations " ". Text in the info object is treated as a "string".
info:
title: "OpenWeatherMap API"
The info object and its properties in a fully filled out menu:
The info object JSON example:
The servers object specifies the path of the url when the API is called. The servers object is the basepath before the endpoint of the URL.
In this case: https://api.openweathermap.org/data/2.5
The endpoint is the end of the path of the URL.
In this case: /weather
The servers object appends the endpoint to the server URL path when the API is called.
https://api.openweathermap.org/data/2.5/weather
Adding a servers object will create a dropdown menu in the Swagger UI layout. Mutiple servers can be added to the menu as needed. If you are doing testing, for example, you may use a test server for some API calls.
The basic format for adding a servers object to the Swagger documentation:
servers:
- url: https://api.openweathermap.org/data/2.5
description: Production server
Adding multiple servers to the servers object dropdown menu:
The servers object JSON example:
The paths object refers to the endpoint of the URL call. The path contains an operation object, a parameters object, a responses object, and possibly more.
The operation object refers to the methods GET, POST, PUT, DELETE, among others. The operation object describes a single action on an API path. For the OpenWeatherMap API there is only one path /weather, and one method get for that path.
Adding the necessary operation object and properties to the OpenWeatherMap API path:
The operation object properties and sub-objects:
| Field Name | Type | Description |
|---|---|---|
| tags | string | A list of tags for organizing API paths. Tags can be used for logical grouping of operations by resources. Swagger UI will group paths by tag headings. |
| summary | string | A short summary of the operation behavior. 5-10 words in length. The summary will display in the Swagger UI menu. |
| description | string | A longer explanation of the operation behavior. CommonMark syntax MAY be used for formatting. |
| externalDocs | External Documentation Object | Optional link to further documentation describing the path. |
| operationId | string | A unique string identifier. The ID MUST be unique among all the operations described by the API. |
| parameters | Parameter Object / Reference Object | A list of parameters to help filter the information the operation returns. If a parameter is defined at the path item, this entry will override it. A unique parameter is described by a name and location. The parameter can also include a reference object that points to the description in the compenents object. |
| requestBody | Request Body Object / Reference Object | The request body parameters for this path. The parameter can also include a reference object that points to the description in the compenents object. Request body parameters are only applicable by cacheable HTTP methods, mainly GET and HEAD. For more information |
| responses | Responses Body Object | REQUIRED. Responses provided with requests from this path. The responses object can also include a reference object that points to the description in the components object. |
| callbacks | Map[string, Callback Object / Reference Object] |
A map of possible callbacks related to the parent operation. Initiated after a method executes. The key value is used to identify the URL for the callback operation. The callback operation can also include a reference object that points to the description in the components object. |
| deprecated | boolean | Declares the operation should be discontinued. The operation SHOULD not be used. Default value is false. |
| security | Security Requirement Object | Declares what authorization method can be used with the operation. Only one security object requirement is needed to authorize a request. This definition overrides the security object at the root-level. An empty array {} can be used to remove a root-level security declaration. |
| servers | Server Object | An alternate server array to service the operation. An alternate server object will override the server declared at the root-level. |
Note: Bold denotes properties and objects necessary for OpenWeatherMap API.
The operation object and its properites before the parameters object is added:
The operation object JSON example:
The parameters object describes a single parameter object. A unique identifier is defined by a name and a location.
There are four possible locations for the parameters object in the in field:
- path - Does not include the basepath of the URL endpoint.
/items/{item_endpoint}Path parameter ={item_endpoint} - query - Parameters that are appended to the URL endpoint.
/items?id=9812Query parameter =id - header - Custom headers that are added to the request. Headers are case sensitive.
- cookie - Passes a specific cookie value to the API.
Adding parameter objects to the Swagger UI. For OpenWeatherMap the parameters object structure is as follows:
The parameters object with search parameter options for city name and city ID.
The parameter object with search parameter options for latitude, longitude, and zip code. Note: Latitude and longitude MUST be used together.
The parameters object with search parameter options for units and language.
The parameters object with search parameter options for the mode of the response.
