Часть 11 из 15 · слайды 87–94

Стандарты реальных команд

Так устроен стандарт учебного проекта. Посмотрим, как это делают OpenAPI Initiative, Zalando, Microsoft и другие.

87Как выглядит сам стандарт
88Большая организация создаёт собственный API standard
89Ещё одна организация — другие правила
90Style Guide + автоматический ruleset
91OpenAPI реального огромного API
92Как организовать большой OpenAPI по файлам
93Правила можно сделать очень строгими
94OpenAPI можно использовать как публичный source of truth

87Как выглядит сам стандарт

Репозиторий OAI/OpenAPI-Specification — место, где развивается спецификация OpenAPI.

Что смотреть	Что там
`README.md`	что такое спецификация и как в ней участвовать
`versions/`	опубликованные редакции: 3.0.x, 3.1.x, 3.2.x
`style-guide.md`	правила оформления текста самой спецификации

Сам технический стандарт тоже развивается как versioned repository: с историей, pull requests и review.

Корень репозитория спецификации: папка versions, README.md и style-guide.md. Клик — увеличить.

88Большая организация создаёт собственный API standard

Zalando опубликовала правила, по которым её команды проектируют REST API.

zalando/restful-api-guidelines

Особенно полезные разделы в папке chapters:

design principles;
HTTP requests;
JSON;
pagination;
security;
deprecation;
compatibility.

Zalando использует API First: спецификация создаётся до реализации и проходит review.

Описание репозитория «A model set of guidelines for RESTful APIs and Events» и папка chapters. Клик — увеличить.

89Ещё одна организация — другие правила

Microsoft публикует общие правила и отдельные правила для двух своих платформ.

microsoft/api-guidelines

Что изучить	Что там
`Guidelines.md`	общие правила Microsoft REST API
`azure/`	правила для сервисов Azure
`graph/`	правила для Microsoft Graph
`CONTRIBUTING.md`	как предлагать изменения

Полезно сравнить правила versioning Microsoft и Zalando.

Корпоративный стандарт не обязан быть одинаковым у всех компаний.

Корень репозитория: Guidelines.md, папки azure и graph. Клик — увеличить.

90Style Guide + автоматический ruleset

В репозитории adidas правило существует одновременно как текст и как автоматическая проверка.

adidas/api-guidelines

Здесь особенно интересна связь Markdown guidelines и правил Spectral. В корне лежат:

Файл	Что это
`ruleset.md`	описание правил для людей
`.spectral.yml`	конфигурация линтера репозитория
`adidas-spectral.yaml`	ruleset, который подключают команды

Это практически прямой пример темы нашей дисциплины.

Файлы adidas-spectral.yaml и ruleset.md в корне репозитория. Клик — увеличить.

91OpenAPI реального огромного API

GitHub публикует OpenAPI description своего REST API.

github/rest-api-description

В репозитории лежит описание сотен операций GitHub REST API. README сообщает, что это описание используется во всём процессе разработки API: по нему проверяются запросы к GitHub API и работают контрактные тесты.

OpenAPI не ограничивается учебными проектами.

Описание репозитория: «An OpenAPI description for GitHub's REST API». Клик — увеличить.

92Как организовать большой OpenAPI по файлам

Redocly/openapi-starter полезен не кодом приложения, а организацией API description.

Redocly/openapi-starter

openapi/
├── openapi.yaml   точка входа
├── paths/         по файлу на адрес
├── components/    схемы, параметры
├── code_samples/
└── webhooks/

Большой OpenAPI необязательно хранить одним огромным YAML. Его разбивают на файлы, а $ref собирает их в один документ.

Папка openapi: openapi.yaml, paths, components, code_samples, webhooks. Клик — увеличить.

93Правила можно сделать очень строгими

В репозитории OpenAPI DigitalOcean есть собственный Spectral ruleset.

digitalocean/openapi → spectral/ruleset.yml

Что проверяется	Правило
rate limit headers	`ratelimit-headers`
examples	`properties-must-include-examples`
operationId naming	`operationid-must-follow-new-naming-conventions`
schema naming	`schema-key-must-be-snake-cased`
security declarations	`oas3-operation-security-defined`

Хороший материал для самостоятельного анализа: откройте файл и найдите, какие проверки вынесены в папку functions.

spectral/ruleset.yml: у правил ratelimit-headers и properties-must-include-examples стоит severity: error. Клик — увеличить.

94OpenAPI можно использовать как публичный source of truth

Box публикует OpenAPI specification своей платформы в открытом репозитории.

box/box-openapi

В корне лежит openapi.json — описание Box Platform API. В папке openapi хранятся отдельные файлы для версий, введённых в 2025 году: openapi-v2025.0.json, openapi-v2026.0.json.

По репозиторию видно, как versioned API descriptions развиваются вместе с API.

Корень репозитория: файл openapi.json и папка openapi. Клик — увеличить.