Каковы основные параметры стабилитрона КС527А. Какие у него характеристики. Где применяется стабилитрон КС527А. Как правильно использовать этот полупроводниковый прибор.
Основные параметры стабилитрона КС527А
Стабилитрон КС527А — это полупроводниковый прибор, предназначенный для стабилизации напряжения. Его основные параметры:
- Номинальное напряжение стабилизации: 27 В
- Максимальный ток стабилизации: 30 мА
- Минимальный ток стабилизации: 1 мА
- Максимальная рассеиваемая мощность: 1000 мВт
- Температурный коэффициент напряжения стабилизации: 10 x 10^-2 %/°C
- Дифференциальное сопротивление: не более 40 Ом
Характеристики и особенности КС527А
Стабилитрон КС527А обладает следующими ключевыми характеристиками:
- Высокая стабильность напряжения в широком диапазоне токов
- Малое дифференциальное сопротивление
- Высокая температурная стабильность
- Малые габариты
- Высокая надежность
Какие преимущества дает использование стабилитрона КС527А? Основное преимущество — возможность получить стабильное опорное напряжение 27 В при изменении входного напряжения или тока нагрузки. Это позволяет создавать надежные источники питания и опорного напряжения.
Области применения стабилитрона КС527А
Стабилитрон КС527А находит широкое применение в различных электронных устройствах и схемах:
- Источники стабилизированного напряжения
- Стабилизаторы напряжения
- Источники опорного напряжения
- Ограничители напряжения
- Схемы защиты от перенапряжений
- Измерительная аппаратура
- Радиоэлектронная аппаратура
Где еще можно использовать КС527А? Этот стабилитрон часто применяется в блоках питания, усилителях, генераторах и других аналоговых схемах, где требуется стабильное опорное напряжение.
Особенности использования стабилитрона КС527А
При использовании стабилитрона КС527А необходимо учитывать некоторые важные моменты:
- Включать стабилитрон следует в обратном направлении — анодом к отрицательному потенциалу.
- Напряжение на стабилитроне не должно превышать максимально допустимое обратное напряжение.
- Ток через стабилитрон должен быть в пределах допустимого диапазона.
- Необходимо обеспечить эффективный теплоотвод при работе на предельных режимах.
- Рекомендуется использовать последовательный токоограничивающий резистор.
Как правильно выбрать номинал ограничительного резистора? Его сопротивление рассчитывается по формуле: R = (Uвх — Uст) / Iст, где Uвх — входное напряжение, Uст — напряжение стабилизации, Iст — ток стабилизации.
Маркировка и корпус КС527А
Стабилитрон КС527А выпускается в стеклянном корпусе DO-35 (аналог отечественного корпуса КД-4). Маркировка на корпусе включает:
- Буквенно-цифровое обозначение КС527А
- Цветная полоса, обозначающая катод
- Возможно нанесение даты изготовления
Как расшифровывается маркировка КС527А? «КС» означает «кремниевый стабилитрон», «527» — порядковый номер разработки, «А» — группа по напряжению стабилизации.
Аналоги стабилитрона КС527А
Стабилитрон КС527А имеет ряд отечественных и зарубежных аналогов:
- Отечественные: 2С527А, Д818Д, КС627А
- Зарубежные: 1N4750A, BZX79C27, ZY27
Чем отличаются аналоги от КС527А? Основные различия могут быть в точности напряжения стабилизации, температурном коэффициенте, максимальном токе и мощности. При замене необходимо внимательно сравнивать параметры.
Проверка работоспособности КС527А
Для проверки исправности стабилитрона КС527А можно выполнить следующие шаги:
- Проверить сопротивление в прямом и обратном направлении мультиметром
- Измерить напряжение стабилизации при номинальном токе
- Проверить стабильность напряжения при изменении тока
- Измерить обратный ток утечки
Какие показатели свидетельствуют о неисправности? Основные признаки — отклонение напряжения стабилизации от номинала более чем на 10%, большой обратный ток утечки, нестабильность напряжения при изменении тока.
Рекомендации по монтажу КС527А
При монтаже стабилитрона КС527А следует соблюдать следующие правила:
- Использовать пинцет при работе с прибором во избежание повреждения статическим электричеством
- Не допускать механических повреждений корпуса и выводов
- Пайку производить в течение не более 3-5 секунд при температуре не выше 260°C
- Обеспечить зазор не менее 1 мм между корпусом прибора и печатной платой
- При необходимости использовать теплоотвод
Как правильно подключить КС527А в схему? Катод стабилитрона (помечен полосой) подключается к более положительному потенциалу, анод — к более отрицательному.
Стабилитрон КС527А
Количество драгоценных металлов в стабилитроне КС527А согласно документации производителя. Справочник массы и наименований ценных металлов в советских стабилитронах КС527А.
Стабилитрон КС527А количество содержания драгоценных металлов:
Золото: 0,00008 грамм.
Серебро: 0,00001 грамм.
Платина: 0 грамм.
Палладий: 0 грамм.
Согласно данным: Из справочника Связь-Инвест.
Справочник содержания ценных металлов из другого источника:
Стабилитроны КС527А теория
Полупроводниковый стабилитрон, или диод Зенера — полупроводниковый диод, работающий при обратном смещении в режиме пробоя. До наступления пробоя через стабилитрон протекают незначительные токи утечки, а его сопротивление весьма высоко. При наступлении пробоя ток через стабилитрон резко возрастает, а его дифференциальное сопротивление падает до величины, составляющей для различных приборов от долей Ома до сотен Ом.
Поэтому в режиме пробоя напряжение на стабилитроне поддерживается с заданной точностью в широком диапазоне обратных токов.
Прежде всего, не следует забывать, что стабилитрон работает только в цепях постоянного тока. Напряжение на стабилитрон подают в обратной полярности, то есть на анод стабилитрона будет подан минус “-“. При таком включении стабилитрона через него протекает обратный ток (I обр) от выпрямителя. Напряжение с выхода выпрямителя может изменяться, будет изменяться и обратный ток, а напряжение на стабилитроне и на нагрузке останется неизменным, то есть стабильным. На следующем рисунке показана вольт-амперная характеристика стабилитрона.
Основное назначение стабилитронов — стабилизация напряжения. Серийные стабилитроны изготавливаются на напряжения от 1,8 В до 400 В. Интегральные стабилитроны со скрытой структурой на напряжение около 7 В являются самыми точными и стабильными твердотельными источниками опорного напряжения: лучшие их образцы приближаются по совокупности показателей к нормальному элементу Вестона.
Особый тип стабилитронов, высоковольтные лавинные диоды («подавители переходных импульсных помех», «суппрессоры», «TVS-диоды») применяется для защиты электроаппаратуры от перенапряжений.
Стабилитроны КС527А Принцип действия
Советские и импортные стабилитроны
Полупроводниковый стабилитрон — это диод, предназначенный для работы в режиме пробоя на обратной ветви вольт-амперной характеристики. В диоде, к которому приложено обратное, или запирающее, напряжение, возможны три механизма пробоя: туннельный пробой, лавинный пробой и пробой вследствие тепловой неустойчивости — разрушительного саморазогрева токами утечки. Тепловой пробой наблюдается в выпрямительных диодах, особенно германиевых, а для кремниевых стабилитронов он не критичен. Стабилитроны проектируются и изготавливаются таким образом, что либо туннельный, либо лавинный пробой, либо оба эти явления вместе возникают задолго до того, как в кристалле диода возникнут предпосылки к тепловому пробою.
Серийные стабилитроны изготавливаются из кремния, известны также перспективные разработки стабилитронов из карбида кремния и арсенида галлия.
Первую модель электрического пробоя предложил в 1933 году Кларенс Зенер, в то время работавший в Бристольском университете. Его «Теория электического пробоя в твёрдых диэлектриках» была опубликована летом 1934 года. В 1954 году Кеннет Маккей из Bell Labs установил, что предложеный Зенером туннельный механизм действует только при напряжениях пробоя до примерно 5,5 В, а при бо́льших напряжениях преобладает лавинный механизм. Напряжение пробоя стабилитрона определяется концентрациями акцепторов и доноров и профилем легирования области p-n-перехода. Чем выше концентрации примесей и чем больше их градиент в переходе, тем больше напряжённость электрического поля в области пространственного заряда при равном обратном напряжении, и тем меньше обратное напряжение, при котором возникает пробой:
Туннельный, или зенеровский, пробой возникает в полупроводнике только тогда, когда напряжённость электрического поля в p-n-переходе достигает уровня в 106 В/см.
В диодах с меньшими уровнями легирования, или меньшими градиентами легирующих примесей, и, как следствие, бо́льшими напряжениями пробоя наблюдается лавинный механизм пробоя. Он возникает при концентрациях примесей, примерно соответствующих напряжению пробоя в 4 EG (≈4,5 В), а при напряжениях пробоя выше 4 EG (≈7,2 В) полностью вытесняет туннельный механизм. Напряжение, при котором возникает лавинный пробой, с ростом температуры возрастает, а наибольшая величина ТКН пробоя наблюдается в низколегированных, относительно высоковольтных, переходах.
Механизм пробоя конкретного образца можно определить грубо — по напряжению стабилизации, и точно — по знаку его температурного коэффициента. В «серой зоне» (см. рисунок), в которой конкурируют оба механизма пробоя, ТКН может быть определён только опытным путём. Источники расходятся в точных оценках ширины этой зоны: С. М. Зи указывает «от 4 EG до 6 EG» (4,5…6,7 В), авторы словаря «Электроника» — «от 5 до 7 В»8, Линден Харрисон — «от 3 до 8 В»26, Ирвинг Готтлиб проводит верхнюю границу по уровню 10 В9. Низковольтные лавинные диоды (LVA) на напряжения от 4 до 10 В — исключение из правила: в них действует только лавинный механизм.
Оптимальная совокупность характеристик стабилитрона достигается в середине «серой зоны», при напряжении стабилизации около 6 В. Дело не столько в том, что благодаря взаимной компенсации ТКН туннельного и лавинного механизмов эти стабилитроны относительно термостабильны, а в том, что они имеют наименьший технологический разброс напряжения стабилизации и наименьшее, при прочих равных условиях, дифференциальное сопротивление.
Область применения стабилитрона КС527А
Основная область применения стабилитрона — стабилизация постоянного напряжения источников питания. В простейшей схеме линейного параметрического стабилизатора стабилитрон выступает одновременно и источником опорного напряжения, и силовым регулирующим элементом. В более сложных схемах стабилитрону отводится только функция источника опорного напряжения, а регулирующим элементом служит внешний силовой транзистор.
Прецизионные термокомпенсированные стабилитроны и стабилитроны со скрытой структурой широко применяются в качестве дискретных и интегральных источников опорного напряжения (ИОН), в том числе в наиболее требовательных к стабильности напряжения схемах измерительных аналого-цифровых преобразователей. C середины 1970-х годов и по сей день (2012 год) стабилитроны со скрытой структурой являются наиболее точными и стабильными твердотельными ИОН.
Точностные показатели лабораторных эталонов напряжения на специально отобранных интегральных стабилитронах приближаются к показателям нормального элемента Вестона.
Особые импульсные лавинные стабилитроны («подавители переходных импульсных помех», «суппрессоры», «TVS-диоды») применяются для защиты электроаппаратуры от перенапряжений, вызываемых разрядами молний и статического электричества, а также от выбросов напряжения на индуктивных нагрузках. Такие приборы номинальной мощностью 1 Вт выдерживают импульсы тока в десятки и сотни ампер намного лучше, чем «обычные» пятидесятиваттные силовые стабилитроны. Для защиты входов электроизмерительных приборов и затворов полевых транзисторов используются обычные маломощные стабилитроны. В современных «умных» МДП-транзисторах защитные стабилитроны выполняются на одном кристалле с силовым транзистором.
Маркировка стабилитронов КС527А
Маркировка стабилитронов
Есть информация о стабилитроне КС527А – высылайте ее нам, мы ее разместим на этом сайте посвященному утилизации, аффинажу и переработке драгоценных и ценных металлов.
Фото Стабилитрон КС527А:
Предназначение Стабилитрон КС527А.
Характеристики Стабилитрон КС527А:
Купить или продать а также цены на Стабилитрон КС527А (стоимость, купить, продать):
Отзыв о стабилитроне КС527А вы можете в комментариях ниже:
- Стабилитроны
| |
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
.. 7,5В… 8,0В…
12,0В… 13,0В… 180,0ВОписание параметров
OAS 3 Эта страница посвящена OpenAPI 3.
0. Если вы используете OpenAPI 2.0, см. наше руководство по OpenAPI 2.0.
В OpenAPI 3.0 параметры определяются в разделе параметров операции или пути. Чтобы описать параметр, вы указываете его имя , местоположение ( в ), тип данных (определяется либо схемой , либо содержимым ) и другие атрибуты, такие как описание или обязательные . Вот пример:
путей:
/пользователи/{userId}:
получать:
резюме: Получить пользователя по ID
параметры:
- в: путь
имя: идентификатор пользователя
схема:
тип: целое число
требуется: правда
описание: Числовой идентификатор пользователя для получения Обратите внимание, что параметров — это массив, поэтому в YAML каждое определение параметра должно быть указано с дефисом ( - ) перед ним.
Типы параметров
OpenAPI 3.
0 различает следующие типы параметров в зависимости от расположения параметра. Расположение определяется ключом параметра в , например, в: запрос или в: путь .
- параметры пути, такие как
/users/{id} - параметра запроса, например
/users?role=admin - параметра заголовка, например
X-MyHeader: Значение - параметры cookie, которые передаются в заголовке
Cookie, например,Cookie: debug=0; csrftoken = BUSe35dohU3O1MZvDCU
Параметры пути
Параметры пути — это переменные части пути URL. Обычно они используются для указания на конкретный ресурс в коллекции, например на пользователя, идентифицируемого по идентификатору. URL-адрес может иметь несколько параметров пути, каждый из которых обозначается фигурными скобками { } .
ПОЛУЧИТЬ /пользователи/{идентификатор}
ПОЛУЧИТЬ /cars/{carId}/drivers/{driverId}
ПОЛУЧИТЬ /отчет.
{формат}
{формат}
Каждый параметр пути должен быть заменен фактическим значением, когда клиент делает вызов API. В OpenAPI параметр пути определяется с помощью в: path . Имя параметра должно совпадать с указанным в пути. Также не забудьте добавить required: true , потому что параметры пути требуются всегда. Например, /users/{id} 9Конечная точка 0008 будет описана как:
путей:
/пользователи/{идентификатор}:
получать:
параметры:
- в: путь
name: id # Обратите внимание, имя такое же, как и в пути
требуется: правда
схема:
тип: целое число
минимум: 1
описание: ID пользователя Параметры пути, содержащие массивы и объекты, могут быть сериализованы по-разному:
- расширение пути (матрица) — с префиксом в виде точки с запятой, например
/map/point;x=50;y=20 Расширение этикетки - — с префиксом в виде точки, например
/color. R=100.G=200.B=150 - в простом стиле — с разделителями-запятыми, например
/users/12,34,56
R=100.G=200.B=150 Метод сериализации определяется ключевыми словами стиля и Expand . Дополнительные сведения см. в разделе Сериализация параметров.
Параметры запроса
Параметры запроса являются наиболее распространенным типом параметров. Они появляются в конце URL-адреса запроса после вопросительного знака ( ? ) с разными парами имя=значение , разделенными амперсандом ( и ). Параметры запроса могут быть обязательными и необязательными.
ПОЛУЧИТЬ /pets/findByStatus?status=доступно
ПОЛУЧИТЬ /notes?offset=100&limit=50 Используйте в: query для обозначения параметров запроса:
параметры:
- в: запрос
имя: смещение
схема:
тип: целое число
описание: Количество элементов, которые следует пропустить перед началом сбора набора результатов.
- в: запрос
Название: лимит
схема:
тип: целое число
описание: Количество возвращаемых элементов 
- в: запрос
Название: лимит
схема:
тип: целое число
описание: Количество возвращаемых элементов Примечание: Чтобы описать ключи API, передаваемые в качестве параметров запроса, используйте securitySchemes и security вместо . См. Ключи API.
Параметры запроса могут быть примитивными значениями, массивами и объектами. OpenAPI 3.0 предоставляет несколько способов сериализации объектов и массивов в строке запроса.
Массивы могут быть сериализованы как:
-
форма–/products?color=blue,green,redили/products?color=blue&color=green, в зависимости от ключевого словаexpire -
пробел с разделителями(то же, что иcollectionFormat: ssvв OpenAPI 2.0) —/products?color=blue%20green%20red -
pipeDelimited(то же, что иcollectionFormat: трубыв OpenAPI 2. 0) — /products?color=blue|green|red
0) — Объекты могут быть сериализованы как:
-
форма–/точки?color=R,100,G,200,B,150или/точки?R=100&G=200&B=150, в зависимости отвзорватьключевое слово -
deepObject–/points?color[R]=100&color[G]=200&color[B]=150
Метод сериализации определяется ключевыми словами стиля и Expand . Дополнительные сведения см. в разделе Сериализация параметров.
Зарезервированные символы в параметрах запроса
RFC 3986 определяет набор зарезервированных символов :/?#[]@!$&'()*+,;= , которые используются в качестве разделителей компонентов URI. Когда эти символы необходимо использовать буквально в значении параметра запроса, они обычно кодируются в процентах.
Например, / кодируется как %2F (или %2f ), поэтому значение параметра quotes/h3g2.txt будет отправлено как
ПОЛУЧИТЬ /file?path=quotes%2Fh3g2.txt Если вам нужен параметр запроса без процентного кодирования, добавьте allowReserved: true в определение параметра:
параметры:
- в: запрос
имя: путь
требуется: правда
схема:
тип: строка
allowReserved: true # <----- В этом случае значение параметра будет отправлено так:
ПОЛУЧИТЬ /file?path=quotes/h3g2.txt Вызов API может потребовать, чтобы настраиваемые заголовки были отправлены с HTTP-запросом. OpenAPI позволяет вам определять пользовательские заголовки запросов как в: параметры заголовка . Например, предположим, что для вызова GET /ping требуется заголовок X-Request-ID :
ПОЛУЧИТЬ /ping HTTP/1. 1
Хост: example.com
Идентификатор X-запроса: 77e1c83b-7bb0-437b-bc50-a7a58e5660ac 
1
Хост: example.com
Идентификатор X-запроса: 77e1c83b-7bb0-437b-bc50-a7a58e5660ac Используя OpenAPI 3.0, вы бы определили эту операцию следующим образом:
путей:
/пинг:
получать:
резюме: проверяет, жив ли сервер
параметры:
- в: заголовок
имя: Идентификатор X-запроса
схема:
тип: строка
формат: UUID
required: true Аналогичным образом вы можете определить собственные заголовки ответов. Параметр заголовка может быть примитивами, массивами и объектами. Массивы и объекты сериализуются с помощью простой стиль . Дополнительные сведения см. в разделе Сериализация параметров.
Примечание. Параметры заголовка с именем Accept , Content-Type и Authorization не допускаются. Для описания этих заголовков используйте соответствующие ключевые слова OpenAPI:
| Заголовок | Ключевые слова OpenAPI | Для получения дополнительной информации см. .. |
|---|---|---|
Тип содержимого | Тип содержимого запроса: requestBody.content. Тип содержимого ответа: | Описание тела запроса, Описание ответов, Типы носителей |
Принять | ответов. | Описание ответов, Типы носителей |
Авторизация | схемы безопасности , безопасность | Аутентификация |
Параметры cookie
Операции также могут передавать параметры в заголовке Cookie , как Cookie: name=value . Несколько параметров cookie отправляются в одном и том же заголовке, разделенные точкой с запятой и пробелом.
ПОЛУЧИТЬ /api/пользователи
Хост: example. com
Куки: отладка=0; csrftoken=BUSe35dohU3O1MZvDCUOJ 
com
Куки: отладка=0; csrftoken=BUSe35dohU3O1MZvDCUOJ Используйте в: cookie для определения параметров cookie:
параметры:
- в: печенье
имя: отладка
схема:
тип: целое число
перечисление: [0, 1]
по умолчанию: 0
- в: печенье
имя: csrftoken
схема:
тип: строка Параметры cookie могут быть примитивными значениями, массивами и объектами. Массивы и объекты сериализуются с помощью форма стиль. Дополнительные сведения см. в разделе Сериализация параметров.
Примечание: Чтобы определить аутентификацию с помощью файлов cookie, вместо этого используйте ключи API.
Обязательные и дополнительные параметры
По умолчанию OpenAPI рассматривает все параметры запроса как необязательные. Вы можете добавить required: true , чтобы пометить параметр как обязательный. Обратите внимание, что параметры пути должны иметь required: true , потому что они всегда требуются.
параметров:
- в: путь
имя: идентификатор пользователя
схема:
тип: целое число
требуется: true # <----------
описание: Числовой идентификатор пользователя, которого нужно получить.
схема и содержимое
Для описания содержимого параметра можно использовать ключевое слово schema или content . Они взаимоисключающие и используются в разных сценариях. В большинстве случаев вы должны использовать схему . Он позволяет описывать примитивные значения, а также простые массивы и объекты, сериализованные в строку. Метод сериализации для параметров массива и объекта определяется стилем и разнести ключевых слов, используемых в этом параметре.
параметров:
- в: запрос
имя: цвет
схема:
тип: массив
Предметы:
тип: строка
# Сериализировать как color=blue,black,brown (по умолчанию)
стиль: форма
взорвать: false content используется в сложных сценариях сериализации, которые не охватываются стилем и взорваться . Например, если вам нужно отправить строку JSON в строке запроса следующим образом:
filter={"тип":"футболка","цвет":"синий"} В этом случае вам необходимо обернуть параметр schema в content/, как показано ниже. Схема определяет структуру данных параметра, а тип носителя (в данном примере — application/json ) служит ссылкой на внешнюю спецификацию, описывающую формат сериализации.
параметров:
- в: запрос
имя: фильтр
# Обернуть 'schema' в 'content.'
содержание:
application/json: # <---- media type указывает, как сериализовать/десериализовать содержимое параметра
схема:
тип: объект
характеристики:
тип:
тип: строка
цвет:
тип: строка Примечание для пользователей пользовательского интерфейса Swagger и редактора Swagger: Параметры с содержимым поддерживаются в пользовательском интерфейсе Swagger 3. 23.7+ и редакторе Swagger 3.6.34+.
Значения параметров по умолчанию
Используйте ключевое слово по умолчанию в схеме параметров, чтобы указать значение по умолчанию для необязательного параметра. Значение по умолчанию — это значение, которое использует сервер, если клиент не предоставляет значение параметра в запросе. Тип значения должен совпадать с типом данных параметра. Типичным примером являются параметры пейджинга, такие как смещение и предел :
ПОЛУЧИТЬ /пользователи
ПОЛУЧИТЬ /users?offset=30&limit=10
Предполагая, что offset по умолчанию равен 0, а limit по умолчанию равен 20 и находится в диапазоне от 0 до 100, вы должны определить эти параметры как:
параметров:
- в: запрос
имя: смещение
схема:
тип: целое число
минимум: 0
по умолчанию: 0
требуется: ложь
описание: количество элементов, которые следует пропустить перед началом сбора набора результатов.
- в: запрос
Название: лимит
схема:
тип: целое число
минимум: 1
максимум: 100
по умолчанию: 20
требуется: ложь
описание: количество возвращаемых элементов. Распространенные ошибки
Есть две распространенные ошибки при использовании ключевого слова по умолчанию :
- Использование
по умолчаниюсобязательнымипараметрами или свойствами, например, с параметрами пути. Это не имеет смысла — если требуется значение, клиент всегда должен его отправить, а значение по умолчанию никогда не используется. - Использование
по умолчаниюдля указания выборочного значения. Это не предназначенное использованиепо умолчаниюи может привести к неожиданному поведению в некоторых инструментах Swagger. Вместо этого используйте ключевое словоexampleилиexamples. См. Добавление примеров.
Параметры перечисления
Вы можете ограничить параметр фиксированным набором значений, добавив перечисление к схеме параметра . Значения перечисления должны быть того же типа, что и тип данных параметра.
параметров:
- в: запрос
имя: статус
схема:
тип: строка
перечисление:
- доступный
- в ожидании
- продано Дополнительная информация: Определение Enum.
Постоянные параметры
Вы можете определить постоянный параметр как обязательный параметр только с одним возможным значением:
параметров:
- в: запрос
имя: rel_date
требуется: правда
схема:
тип: строка
перечисление:
- теперь Свойство enum задает возможные значения. В этом примере можно использовать только одно значение, и это будет единственное значение, доступное в пользовательском интерфейсе Swagger для выбора пользователем.
Примечание: Постоянный параметр не совпадает со значением параметра по умолчанию. Постоянный параметр всегда отправляется клиентом, тогда как значение по умолчанию — это то, что использует сервер, если параметр не отправляется клиентом.
Пустые и нулевые параметры
Параметры строки запроса могут иметь только имя и не иметь значения, например:
ПОЛУЧИТЬ /foo?метаданные Используйте allowEmptyValue для описания таких параметров:
параметров:
- в: запрос
имя: метаданные
схема:
тип: логический
allowEmptyValue: true # <----- OpenAPI 3.0 также поддерживает nullable в схемах, позволяя параметрам операции иметь значение null . Например, следующая схема соответствует int? в С# и java.lang.Integer в Java:
схема:
тип: целое число
формат: int32
nullable: true Примечание: nullable — это не то же самое, что необязательный параметр или параметр с пустым значением. nullable означает, что значение параметра может быть null . Конкретные реализации могут сопоставлять отсутствующий или пустой параметр с null , но, строго говоря, это не одно и то же.
Примеры параметров
Для параметра можно указать пример или несколько примеров . Значение примера должно соответствовать схеме параметра. Один пример:
параметров:
- в: запрос
Название: лимит
схема:
тип: целое число
минимум: 1
пример: 20 Несколько именованных примеров:
параметры:
- в: запрос
имя: идентификаторы
описание: один или несколько идентификаторов
требуется: правда
схема:
тип: массив
Предметы:
тип: целое число
стиль: форма
взорваться: ложь
Примеры:
один идентификатор:
резюме: пример одного идентификатора
значение: [5] # ?ids=5
несколько идентификаторов:
резюме: пример нескольких идентификаторов
значение: [1, 5, 7] # ?ids=1,5,7 Дополнительные сведения см. в разделе Добавление примеров.
Устаревшие параметры
Используйте deprecated: true , чтобы пометить параметр как устаревший.
- в: запрос
имя: формат
требуется: правда
схема:
тип: строка
перечисление: [json, xml, yaml]
устарело: правда
описание: Устарело, вместо этого используйте соответствующий заголовок `Accept`. Общие параметры
Общие параметры для всех методов пути
Параметры, общие для всех операций пути, могут быть определены на уровне пути, а не на уровне операции. Параметры уровня пути наследуются всеми операциями этого пути. Типичным вариантом использования являются операции GET/PUT/PATCH/DELETE, которые манипулируют ресурсом, доступ к которому осуществляется через параметр пути.
путей:
/Идентификатор пользователя}:
параметры:
- в: путь
имя: идентификатор
схема:
тип: целое число
требуется: правда
описание: ID пользователя
получать:
резюме: Получает пользователя по идентификатору
. ..
пластырь:
сводка: обновляет существующего пользователя с указанным идентификатором
...
удалять:
резюме: удаляет пользователя с указанным идентификатором
... Любые дополнительные параметры, определенные на уровне операции, используются вместе с параметрами уровня пути:
путей:
/пользователи/{идентификатор}:
параметры:
- в: путь
имя: идентификатор
схема:
тип: целое число
требуется: правда
описание: идентификатор пользователя.
# GET/users/{id}?metadata=true
получать:
резюме: Получает пользователя по идентификатору
# Обратите внимание, что мы определяем только параметр запроса, поскольку {id} определяется на уровне пути.
параметры:
- в: запрос
имя: метаданные
схема:
тип: логический
требуется: ложь
описание: если true, конечная точка возвращает только пользовательские метаданные.
ответы:
«200»:
Описание: ОК Конкретные параметры уровня пути могут быть переопределены на уровне операции, но не могут быть удалены.
путей:
/пользователи/{идентификатор}:
параметры:
- в: путь
имя: идентификатор
схема:
тип: целое число
требуется: правда
описание: идентификатор пользователя.
# УДАЛИТЬ /users/{id} — используется один идентификатор.
# Повторно использует определение параметра {id} с уровня пути.
удалять:
резюме: Удаляет пользователя с указанным идентификатором.
ответы:
«204»:
Описание: Пользователь удален.
# GET /users/id1,id2,id3 — использует один или несколько идентификаторов пользователей.
# Переопределяет параметр {id} на уровне пути.
получать:
сводка: получает одного или нескольких пользователей по идентификатору.
параметры:
- в: путь
имя: идентификатор
требуется: правда
описание: список идентификаторов пользователей, разделенных запятыми.
схема:
тип: массив
Предметы:
тип: целое число
Минимальные предметы: 1
взорваться: ложь
стиль: простой
ответы:
«200»:
Описание: ОК Общие параметры для различных путей
Различные пути API могут иметь общие параметры, например параметры разбиения на страницы. Вы можете определить общие параметры в параметрах в разделе глобальных компонентов и ссылаться на них в другом месте через $ref .
компонентов:
параметры:
offsetParam: # <-- Произвольное имя определения, которое будет использоваться для ссылки на него.
# Не обязательно совпадает с именем параметра.
в: запрос
имя: смещение
требуется: ложь
схема:
тип: целое число
минимум: 0
описание: количество элементов, которые следует пропустить перед началом сбора набора результатов.
limitПарам:
в: запрос
Название: лимит
требуется: ложь
схема:
тип: целое число
минимум: 1
максимум: 50
по умолчанию: 20
описание: количество возвращаемых элементов.
пути:
/пользователи:
получать:
резюме: Получает список пользователей.
параметры:
- $ref: '#/компоненты/параметры/параметр смещения'
- $ref: '#/компоненты/параметры/limitParam'
ответы:
«200»:
описание: хорошо
/команды:
получать:
резюме: Получает список команд.
параметры:
- $ref: '#/компоненты/параметры/параметр смещения'
- $ref: '#/компоненты/параметры/limitParam'
ответы:
«200»:
Описание: ОК Обратите внимание, что параметры, определенные в компонентах , не являются параметрами, применяемыми ко всем операциям — это просто глобальные определения, которые можно легко использовать повторно.
Зависимости параметров
OpenAPI 3.0 не поддерживает зависимости параметров и взаимоисключающие параметры. На https://github.com/OAI/OpenAPI-Specification/issues/256 есть открытый запрос функции. Что вы можете сделать, так это задокументировать ограничения в описании параметра и определить логику в ответе 400 Bad Request. Например, рассмотрим /report конечная точка, которая принимает либо относительный диапазон дат ( rdate ), либо точный диапазон ( start_date + end_date ):
ПОЛУЧИТЬ /отчет?rdate=Сегодня
ПОЛУЧИТЬ /отчет?start_date=2016-11-15&end_date=2016-11-20 Вы можете описать эту конечную точку следующим образом:
путей:
/отчет:
получать:
параметры:
- имя: рдата
в: запрос
схема:
тип: строка
описание: >
Относительный диапазон дат для отчета, например «Сегодня» или «Последняя неделя».