| Шаг 1: объект openapi | --> | Шаг 2: объект info | --> | Шаг 3: объект servers | --> | Шаг 4: объект paths | --> | Шаг 5: объект components | --> | Шаг 6: объект security | --> | Шаг 7: объект tags | --> | Шаг 8: объект externalDocs |
Объект components уникален среди других объектов в спецификации OpenAPI. В components хранятся переиспользуемые определения, которые могут появляться в нескольких местах в документе спецификации. В нашем сценарии документации API мы будем хранить детали для объектов parameters и responses в объекте components.
Причины использования объекта components
Переиспользование параметров в нескольких путях
Переиспользование объектов responses
Способ обмануть - автоматически генерировать схему из JSON, используя Stoplight
Использование GUI редакторов для работы с кодом спецификации
Раздел Models - почему он существует, как его скрыть
Описание деталей параметров и схемы сложных ответов может быть наиболее сложным аспектом спецификации OpenAPI. Хотя можно определить параметры и ответы непосредственно в объектах параметров и ответов, как правило, они не перечисляются там по двум причинам:
- Возможно, будет желание переиспользовать части этих определений в других запросах или ответах. Обычно один и тот же параметр или ответ используется в нескольких местах в API. С помощью объекта
componentsOpenAPI позволяет вам повторно использовать одни и те же определения в нескольких местах. - Возможно, не захочется загромождать свой объект
pathsслишком большим количеством параметров и подробностей ответа, поскольку объектpathsуже и так сложен из-за нескольких уровней объектов.
Вместо перечисления схемы для ваших запросов и ответов в объекте paths, для более сложных схем (или для схем, которые повторно используются в нескольких операциях или путях), используется объект reference (со ссылкой $ref), который указывает на конкретное определение в объекте components. (Подробнее о $ref см. В разделе Использование $ref.)
Объект components можно представить как о приложении к документу, в котором предоставлены данные для повторного использования. Если несколько частей спецификации имеют одну и ту же схему, можно указывать ссылку на один и тот же объект в объекте components, и при этом вы получаете единый источник контента. Объект components может даже храниться в отдельном файле, для более простой организации информации в больших API. (онлайн-редактор Swagger не позволяет использовать несколько файлов для проверки содержимого.)
В объекте components можно хранить множество различных переиспользуемых объектов. Объект components может содержать следующее:
Свойства каждого объекта внутри components такие же, как и при использовании в других частях спецификации OpenAPI. Используется указатель ссылки ($ref), чтобы указать больше деталей в объекте components. $ref обозначает объект reference и является частью JSON.
На предыдущем шаге Для параметров мы перечислили все детали непосредственно в объекте parameters. Чтобы облегчить переиспользование тех же параметров в других путях, давайте сохраним содержимое parameters в components. Код ниже показывает, как сделать эти ссылки:
paths:
/weather:
get:
tags:
- Current Weather Data
summary: "Call current weather data for one location"
description: "Access current weather data for any location on Earth including over 200,000 cities! Current weather is frequently updated based on global models and data from more than 40,000 weather stations."
operationId: CurrentWeatherData
parameters:
- $ref: '#/components/parameters/q'
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lon'
- $ref: '#/components/parameters/zip'
- $ref: '#/components/parameters/units'
- $ref: '#/components/parameters/lang'
- $ref: '#/components/parameters/mode'
responses:
200:
description: Successful response
content:
application/json:
schema:
title: Sample
type: object
properties:
placeholder:
type: string
description: Placeholder description
404:
description: Not found response
content:
text/plain:
schema:
title: Weather not found
type: string
example: Not found
components:
parameters:
q:
name: q
in: query
description: "**City name**. *Example: London*. You can call by city name, or by city name and country code. The API responds with a list of results that match a searching word. For the query value, type the city name and optionally the country code divided by a comma; use ISO 3166 country codes."
schema:
type: string
id:
name: id
in: query
description: "**City ID**. *Example: `2172797`*. You can call by city ID. The API responds with the exact result. The List of city IDs can be downloaded [here](http://bulk.openweathermap.org/sample/). You can include multiple cities in this parameter — just separate them by commas. The limit of locations is 20. *Note: A single ID counts as a one API call. So, if you have city IDs, it's treated as 3 API calls.*"
schema:
type: string
lat:
name: lat
in: query
description: "**Latitude**. *Example: 35*. The latitude coordinate of the location of your interest. Must use with `lon`."
schema:
type: string
lon:
name: lon
in: query
description: "**Longitude**. *Example: 139*. Longitude coordinate of the location of your interest. Must use with `lat`."
schema:
type: string
zip:
name: zip
in: query
description: "**Zip code**. Search by zip code. *Example: 95050,us*. Please note that if the country is not specified, the search uses USA as a default."
schema:
type: string
units:
name: units
in: query
description: '**Units**. *Example: imperial*. Possible values: `standard`, `metric`, and `imperial`. When you do not use the `units` parameter, the format is `standard` by default.'
schema:
type: string
enum: [standard, metric, imperial]
default: "imperial"
lang:
name: lang
in: query
description: '**Language**. *Example: en*. You can use lang parameter to get the output in your language. We support the following languages that you can use with the corresponded lang values: Arabic - `ar`, Bulgarian - `bg`, Catalan - `ca`, Czech - `cz`, German - `de`, Greek - `el`, English - `en`, Persian (Farsi) - `fa`, Finnish - `fi`, French - `fr`, Galician - `gl`, Croatian - `hr`, Hungarian - `hu`, Italian - `it`, Japanese - `ja`, Korean - `kr`, Latvian - `la`, Lithuanian - `lt`, Macedonian - `mk`, Dutch - `nl`, Polish - `pl`, Portuguese - `pt`, Romanian - `ro`, Russian - `ru`, Swedish - `se`, Slovak - `sk`, Slovenian - `sl`, Spanish - `es`, Turkish - `tr`, Ukrainian - `ua`, Vietnamese - `vi`, Chinese Simplified - `zh_cn`, Chinese Traditional - `zh_tw`.'
schema:
type: string
enum: [ar, bg, ca, cz, de, el, en, fa, fi, fr, gl, hr, hu, it, ja, kr, la, lt, mk, nl, pl, pt, ro, ru, se, sk, sl, es, tr, ua, vi, zh_cn, zh_tw]
default: "en"
mode:
name: mode
in: query
description: "**Mode**. *Example: html*. Determines the format of the response. Possible values are `xml` and `html`. If the mode parameter is empty, the format is `json` by default."
schema:
type: string
enum: [json, xml, html]
default: "json"Заменим существующий объект paths в редакторе Swagger приведенным выше примером кода, включив новый объект components и обратим внимание, что отображаемое изображение по-прежнему выглядит так же.
В шаге 4: объект paths, когда мы описывали объект responses в объекте paths, даже с помощью простого заполнителя, мы использовали объект schema для описания модели запроса или ответа. schema относится к структуре данных (поля, значения и иерархия различных объектов и свойств объекта JSON или YAML - см. Что такое схема?).
Давайте поглубже изучим то, как использовать свойства схемы для документирования объекта response. Мы также будем хранить содержимое схемы в components, чтобы его можно было повторно использовать в других частях документа спецификации. Если вспомнить предыдущий шаг, объект ответов для конечной точки погоды выглядел так:
paths:
/current:
get:
parameters:
...
responses:
200:
description: Successful response
content:
application/json:
schema:
title: Sample
type: object
properties:
placeholder:
type: string
description: Placeholder description
404:
description: Not found response
content:
text/plain:
schema:
title: Weather not found
type: string
example: Not foundПеренесем описание schema для ответа 200 в объект components:
paths:
/weather:
get:
tags:
- Current Weather Data
summary: "Call current weather data for one location"
description: "Access current weather data for any location on Earth including over 200,000 cities! Current weather is frequently updated based on global models and data from more than 40,000 weather stations."
operationId: CurrentWeatherData
parameters:
- $ref: '#/components/parameters/q'
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lon'
- $ref: '#/components/parameters/zip'
- $ref: '#/components/parameters/units'
- $ref: '#/components/parameters/lang'
- $ref: '#/components/parameters/mode'
responses:
200:
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/200'
404:
description: Not found response
content:
text/plain:
schema:
title: Weather not found
type: string
example: Not foundЗатем в components/schemas мы определим схему 200.
Прежде чем мы опишем ответ в объекте components, может быть полезно посмотреть, как выглядит ответ weather от API OpenWeatherMap. Ответ JSON содержит несколько вложенных объектов на разных уровнях.
{
"coord": {
"lon": 145.77,
"lat": -16.92
},
"weather": [
{
"id": 803,
"main": "Clouds",
"description": "broken clouds",
"icon": "04n"
}
],
"base": "cmc stations",
"main": {
"temp": 293.25,
"pressure": 1019,
"humidity": 83,
"temp_min": 289.82,
"temp_max": 295.37,
"sea_level": 984,
"grnd_level": 990
},
"wind": {
"speed": 5.1,
"deg": 150
},
"clouds": {
"all": 75
},
"rain": {
"3h": 3
},
"snow": {
"3h": 6
},
"dt": 1435658272,
"sys": {
"type": 1,
"id": 8166,
"message": 0.0166,
"country": "AU",
"sunrise": 1435610796,
"sunset": 1435650870
},
"id": 2172797,
"name": "Cairns",
"cod": 200
}Существует несколько способов описания этого ответа. Можно создать длинное описание, содержащее всю отраженную иерархию. Однако одной из проблем такого подхода является то, что трудно поддерживать все уровни на одном уровне. С таким количеством вложенных объектов это головокружительно запутанно. Кроме того, легко ошибиться. Хуже всего то, что нельзя переиспользовать отдельные объекты. В первую очередь это подрывает одну из основных причин хранения этого объекта в components.
Другой подход заключается в том, чтобы сделать каждый объект своей сущностью в components. Когда объект содержит объект, добавьте значение $ref, которое указывает на новый объект. Таким образом, объекты остаются неглубокими (вместо нескольких уровней вложенности), и мы не потеряемся в море запутанных подуровней. (Если подобъекта нет, просто предоставим описание напрямую, без использования $ref.
Вот описание ответа 200 для конечной точки weather. Я включил тег paths для поддержания контекста:
Объект responses с документацией components:
paths:
/weather:
get:
tags:
- Current Weather Data
summary: "Call current weather data for one location"
description: "Access current weather data for any location on Earth including over 200,000 cities! Current weather is frequently updated based on global models and data from more than 40,000 weather stations."
operationId: CurrentWeatherData
parameters:
- $ref: '#/components/parameters/q'
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lon'
- $ref: '#/components/parameters/zip'
- $ref: '#/components/parameters/units'
- $ref: '#/components/parameters/lang'
- $ref: '#/components/parameters/mode'
responses:
200:
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/200'
404:
description: Not found response
content:
text/plain:
schema:
title: Weather not found
type: string
example: Not found
components:
parameters:
# not shown for the sake of brevity -- see the earlier code block for details
...
schemas:
200:
title: Successful response
type: object
properties:
coord:
$ref: '#/components/schemas/Coord'
weather:
type: array
items:
$ref: '#/components/schemas/Weather'
description: (more info Weather condition codes)
base:
type: string
description: Internal parameter
example: cmc stations
main:
$ref: '#/components/schemas/Main'
visibility:
type: integer
description: Visibility, meter
example: 16093
wind:
$ref: '#/components/schemas/Wind'
clouds:
$ref: '#/components/schemas/Clouds'
rain:
$ref: '#/components/schemas/Rain'
snow:
$ref: '#/components/schemas/Snow'
dt:
type: integer
description: Time of data calculation, unix, UTC
format: int32
example: 1435658272
sys:
$ref: '#/components/schemas/Sys'
id:
type: integer
description: City ID
format: int32
example: 2172797
name:
type: string
example: Cairns
cod:
type: integer
description: Internal parameter
format: int32
example: 200
Coord:
title: Coord
type: object
properties:
lon:
type: number
description: City geo location, longitude
example: 145.77000000000001
lat:
type: number
description: City geo location, latitude
example: -16.920000000000002
Weather:
title: Weather
type: object
properties:
id:
type: integer
description: Weather condition id
format: int32
example: 803
main:
type: string
description: Group of weather parameters (Rain, Snow, Extreme etc.)
example: Clouds
description:
type: string
description: Weather condition within the group
example: broken clouds
icon:
type: string
description: Weather icon id
example: 04n
Main:
title: Main
type: object
properties:
temp:
type: number
description: 'Temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit.'
example: 293.25
pressure:
type: integer
description: Atmospheric pressure (on the sea level, if there is no sea_level or grnd_level data), hPa
format: int32
example: 1019
humidity:
type: integer
description: Humidity, %
format: int32
example: 83
temp_min:
type: number
description: 'Minimum temperature at the moment. This is deviation from current temp that is possible for large cities and megalopolises geographically expanded (use these parameter optionally). Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit.'
example: 289.81999999999999
temp_max:
type: number
description: 'Maximum temperature at the moment. This is deviation from current temp that is possible for large cities and megalopolises geographically expanded (use these parameter optionally). Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit.'
example: 295.37
sea_level:
type: number
description: Atmospheric pressure on the sea level, hPa
example: 984
grnd_level:
type: number
description: Atmospheric pressure on the ground level, hPa
example: 990
Wind:
title: Wind
type: object
properties:
speed:
type: number
description: 'Wind speed. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour.'
example: 5.0999999999999996
deg:
type: integer
description: Wind direction, degrees (meteorological)
format: int32
example: 150
Clouds:
title: Clouds
type: object
properties:
all:
type: integer
description: Cloudiness, %
format: int32
example: 75
Rain:
title: Rain
type: object
properties:
3h:
type: integer
description: Rain volume for the last 3 hours
format: int32
example: 3
Snow:
title: Snow
type: object
properties:
3h:
type: number
description: Snow volume for the last 3 hours
example: 6
Sys:
title: Sys
type: object
properties:
type:
type: integer
description: Internal parameter
format: int32
example: 1
id:
type: integer
description: Internal parameter
format: int32
example: 8166
message:
type: number
description: Internal parameter
example: 0.0166
country:
type: string
description: Country code (GB, JP etc.)
example: AU
sunrise:
type: integer
description: Sunrise time, unix, UTC
format: int32
example: 1435610796
sunset:
type: integer
description: Sunset time, unix, UTC
format: int32
example: 1435650870 Пояснение, как описать ответ будет в следующих разделах. Взглянув на приведенный выше код, стало заметно, что можно использовать не только свойства $ref в других частях вашей спецификации, но и внутри components.
Обратите внимание, как определение схемы включает в себя свойство
exampleдля каждого элемента? Swagger UI возьмет этотexampleи использует его для динамического построения полного образца кода в секции «Ответы» в выводе пользовательского интерфейса Swagger. Таким образом, не нужны большие куски кода для примеров ответов в нашей спецификации. Вместо этого эти примеры ответов создаются автоматически из схемы. Это одна из приятных вещей в Swagger UI. Таким образом, документация схемы и пример ответа остаются консистентными.
Для большинства разделов в components описаниям объектов тем же, что подробно описаны в остальной части спецификации. При описании объекта schema используются стандартные ключевые слова и термины из схемы JSON, в частности из спецификации JSON Schema Wright Draft 00.
Другими словами, мы не просто используем термины, определенные в спецификации OpenAPI, для описания моделей вашего JSON. При описании своей модели JSON (структуры данных для входных и выходных объектов), терминология в спецификации OpenAPI вводится в более широкие определения JSON и язык описания для моделирования JSON. Использование OpenAPI схемы JSON является лишь подмножеством полной схемы JSON.
Спецификация OpenAPI не пытается документировать, как моделировать схемы JSON. Это было бы излишним, т.к. уже все задокументировано на сайте схемы JSON и выходило бы за рамки спецификации OpenAPI. Поэтому может понадобиться обратиться к схеме JSON для получения более подробной информации. (Еще одно полезное руководство - Расширенные данные из API Handyman.)
Для описания JSON объектов можно использовать следующие идентификаторы:
title;multipleOf;maximum;exclusiveMaximum;minimum;exclusiveMinimum;maxLength;minLength;pattern;maxItems;minItems;uniqueItems;maxProperties;minProperties;required;enum;type;allOf;oneOf;anyOf;not;items;properties;additionalProperties;description;format;default
Доступные типы данных:
integer;long;float;double;string;byte;binary;boolean;date;dateTime;password.
При документировании схемы, лучше начинать с просмотра объекта schema OpenAPI, а потом, если что-то не покрыто, обратиться к схеме JSON.
Кроме того, посмотрите на некоторые примеры схем. Вы можете посмотреть примеры 3.0 здесь. Обычно находят подходящую спецификацию, и имитируют те же свойства и структуру.
Объект
schemaв версии 3.0 немного отличается от объекта схемы в версии 2.0 - см. статью о скандинавских API чтобы понять новинки. Тем не менее, примеры схем из спецификаций 2.0 (которые более распространены в сети), также будут полезны, если просто посмотреть на определения схемы, а не на остальную часть спецификации.
Описание ответа JSON бывает сложным и запутанным. К счастью, есть несколько простой обходной путь. Можно загрузить Stoplight и использовать функцию Generate JSON, чтобы Stoplight автоматически создавал описание схемы OpenAPI. Вот ссылка на короткое видео, показывающее, как это сделать:
По сути, в редактор Stoplight копируется JSON-ответ, который нужно задокументировать. Затем надо нажать Generate JSON. Перейти в представление кода и скопировать JSON. Затем сконвертировать JSON в YAML с помощью онлайн-конвертера. Для получения дополнительной информации см. Stoplight - инструменты визуального моделирования для создания спецификации OpenAPI.
Единственная загвоздка в том, что Stoplight использует OpenAPI 2.0, а не 3.0. Возможно, придется использовать API Transformer для преобразования вывода схемы 2.0 в 3.0. Несмотря на это, такой подход может сэкономить много времени.
На данный момент наверное, есть мысли, насколько будет непрактично и подвержено ошибкам, поскольку работа непосредственно с кодом YAML. По этой причине несколько компаний разработали графические редакторы, чтобы упростить работу с кодом спецификации. В частности, обратите внимание на Stoplight, который предоставляет редактор, позволяющий переключаться между кодом и графическим интерфейсом. Smartbear также предлагает SwaggerHub, который не обязательно предоставляет графический интерфейс, но предоставляет встроенные инструменты комментирования и управления версиями.
Скопируем код ниже и вставим его в редактор Swagger после объектов openapi, info и servers
paths:
/weather:
get:
tags:
- Current Weather Data
summary: "Call current weather data for one location"
description: "Access current weather data for any location on Earth including over 200,000 cities! Current weather is frequently updated based on global models and data from more than 40,000 weather stations."
operationId: CurrentWeatherData
parameters:
- $ref: '#/components/parameters/q'
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lon'
- $ref: '#/components/parameters/zip'
- $ref: '#/components/parameters/units'
- $ref: '#/components/parameters/lang'
- $ref: '#/components/parameters/mode'
responses:
200:
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/200'
404:
description: Not found response
content:
text/plain:
schema:
title: Weather not found
type: string
example: Not found
components:
parameters:
q:
name: q
in: query
description: "**City name**. *Example: London*. You can call by city name, or by city name and country code. The API responds with a list of results that match a searching word. For the query value, type the city name and optionally the country code divided by a comma; use ISO 3166 country codes."
schema:
type: string
id:
name: id
in: query
description: "**City ID**. *Example: `2172797`*. You can call by city ID. The API responds with the exact result. The List of city IDs can be downloaded [here](http://bulk.openweathermap.org/sample/). You can include multiple cities in this parameter — just separate them by commas. The limit of locations is 20. *Note: A single ID counts as a one API call. So, if you have city IDs, it's treated as 3 API calls.*"
schema:
type: string
lat:
name: lat
in: query
description: "**Latitude**. *Example: 35*. The latitude coordinate of the location of your interest. Must use with `lon`."
schema:
type: string
lon:
name: lon
in: query
description: "**Longitude**. *Example: 139*. Longitude coordinate of the location of your interest. Must use with `lat`."
schema:
type: string
zip:
name: zip
in: query
description: "**Zip code**. Search by zip code. *Example: 95050,us*. Please note that if the country is not specified, the search uses USA as a default."
schema:
type: string
units:
name: units
in: query
description: '**Units**. *Example: imperial*. Possible values: `standard`, `metric`, and `imperial`. When you do not use the `units` parameter, the format is `standard` by default.'
schema:
type: string
enum: [standard, metric, imperial]
default: "imperial"
lang:
name: lang
in: query
description: '**Language**. *Example: en*. You can use lang parameter to get the output in your language. We support the following languages that you can use with the corresponded lang values: Arabic - `ar`, Bulgarian - `bg`, Catalan - `ca`, Czech - `cz`, German - `de`, Greek - `el`, English - `en`, Persian (Farsi) - `fa`, Finnish - `fi`, French - `fr`, Galician - `gl`, Croatian - `hr`, Hungarian - `hu`, Italian - `it`, Japanese - `ja`, Korean - `kr`, Latvian - `la`, Lithuanian - `lt`, Macedonian - `mk`, Dutch - `nl`, Polish - `pl`, Portuguese - `pt`, Romanian - `ro`, Russian - `ru`, Swedish - `se`, Slovak - `sk`, Slovenian - `sl`, Spanish - `es`, Turkish - `tr`, Ukrainian - `ua`, Vietnamese - `vi`, Chinese Simplified - `zh_cn`, Chinese Traditional - `zh_tw`.'
schema:
type: string
enum: [ar, bg, ca, cz, de, el, en, fa, fi, fr, gl, hr, hu, it, ja, kr, la, lt, mk, nl, pl, pt, ro, ru, se, sk, sl, es, tr, ua, vi, zh_cn, zh_tw]
default: "en"
mode:
name: mode
in: query
description: "**Mode**. *Example: html*. Determines the format of the response. Possible values are `xml` and `html`. If the mode parameter is empty, the format is `json` by default."
schema:
type: string
enum: [json, xml, html]
default: "json"
schemas:
200:
title: Successful response
type: object
properties:
coord:
$ref: '#/components/schemas/Coord'
weather:
type: array
items:
$ref: '#/components/schemas/Weather'
description: (more info Weather condition codes)
base:
type: string
description: Internal parameter
example: cmc stations
main:
$ref: '#/components/schemas/Main'
visibility:
type: integer
description: Visibility, meter
example: 16093
wind:
$ref: '#/components/schemas/Wind'
clouds:
$ref: '#/components/schemas/Clouds'
rain:
$ref: '#/components/schemas/Rain'
snow:
$ref: '#/components/schemas/Snow'
dt:
type: integer
description: Time of data calculation, unix, UTC
format: int32
example: 1435658272
sys:
$ref: '#/components/schemas/Sys'
id:
type: integer
description: City ID
format: int32
example: 2172797
name:
type: string
example: Cairns
cod:
type: integer
description: Internal parameter
format: int32
example: 200
Coord:
title: Coord
type: object
properties:
lon:
type: number
description: City geo location, longitude
example: 145.77000000000001
lat:
type: number
description: City geo location, latitude
example: -16.920000000000002
Weather:
title: Weather
type: object
properties:
id:
type: integer
description: Weather condition id
format: int32
example: 803
main:
type: string
description: Group of weather parameters (Rain, Snow, Extreme etc.)
example: Clouds
description:
type: string
description: Weather condition within the group
example: broken clouds
icon:
type: string
description: Weather icon id
example: 04n
Main:
title: Main
type: object
properties:
temp:
type: number
description: 'Temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit.'
example: 293.25
pressure:
type: integer
description: Atmospheric pressure (on the sea level, if there is no sea_level or grnd_level data), hPa
format: int32
example: 1019
humidity:
type: integer
description: Humidity, %
format: int32
example: 83
temp_min:
type: number
description: 'Minimum temperature at the moment. This is deviation from current temp that is possible for large cities and megalopolises geographically expanded (use these parameter optionally). Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit.'
example: 289.81999999999999
temp_max:
type: number
description: 'Maximum temperature at the moment. This is deviation from current temp that is possible for large cities and megalopolises geographically expanded (use these parameter optionally). Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit.'
example: 295.37
sea_level:
type: number
description: Atmospheric pressure on the sea level, hPa
example: 984
grnd_level:
type: number
description: Atmospheric pressure on the ground level, hPa
example: 990
Wind:
title: Wind
type: object
properties:
speed:
type: number
description: 'Wind speed. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour.'
example: 5.0999999999999996
deg:
type: integer
description: Wind direction, degrees (meteorological)
format: int32
example: 150
Clouds:
title: Clouds
type: object
properties:
all:
type: integer
description: Cloudiness, %
format: int32
example: 75
Rain:
title: Rain
type: object
properties:
3h:
type: integer
description: Rain volume for the last 3 hours
format: int32
example: 3
Snow:
title: Snow
type: object
properties:
3h:
type: number
description: Snow volume for the last 3 hours
example: 6
Sys:
title: Sys
type: object
properties:
type:
type: integer
description: Internal parameter
format: int32
example: 1
id:
type: integer
description: Internal parameter
format: int32
example: 8166
message:
type: number
description: Internal parameter
example: 0.0166
country:
type: string
description: Country code (GB, JP etc.)
example: AU
sunrise:
type: integer
description: Sunrise time, unix, UTC
format: int32
example: 1435610796
sunset:
type: integer
description: Sunset time, unix, UTC
format: int32
example: 1435650870
securitySchemes:
app_id:
type: apiKey
description: API key to authorize requests. If you don't have an OpenWeatherMap API key, use `fd4698c940c6d1da602a70ac34f0b147`.
name: appid
in: queryВ Swagger UI мы увидим следующее:
Объект
Responsesобъявлен вcomponents
В секции Responses просмотрим, как код Example Value был динамически построен из значений example в схеме, чтобы показать пример ответа.
А еще, кликнем ссылку Model , чтобы увидеть, как описания каждого элемента отображаются в развертываемом / раскладываемом виде:
Отображение описания в Model
Под всеми эндпоинтами расположен раздел «Модели»:
По умолчанию Swagger UI отображает каждый объект из components в разделе «Модели» в конце интерфейса Swagger UI. Если объединить все схемы в один объект, не используя свойство $ref для указания на новые объекты, то будет виден только один объект в моделях. Если разделить объекты, то будет виден каждый объект, перечисленный отдельно, включая объект, который содержит все ссылки.
Для переиспользования объектов, определяем каждый объект в components отдельно. В результате раздел Модели выглядит как на картинке выше
Почему здесь есть раздел моделей? По-видимому, он был добавлен по популярному запросу, потому что онлайн-редактор Swagger показывал дисплей, и многие пользователи просили включить его в интерфейс Swagger.
Раздел «Модели» не нужен в Swagger UI, поскольку в разделах «Запрос» и «Ответ» пользовательского интерфейса Swagger имеется ссылка «Модель», которая позволяет пользователю переключаться в это представление.
Чтобы скрыть раздел «Модели» можно добавить параметр defaultModelsExpandDepth: -1 в проект Swagger UI. В этом модуле есть раздел Руководство Swagger UI, в котором подробно описаны параметры Swagger UI, в которых можно настроить этот параметр.
Объект components также содержит объект securitySchemes, который определяет метод авторизации, используемый с каждым путем. Не будем углубляться в детали конфигурации безопасности, исследуем security на шаге 6: объект security.