Как стыкуется описание JSON и OpenAPI?

OpenAPI — это спецификация для описания REST API, которая использует JSON или YAML для структурирования описания API. В OpenAPI описание данных (payload) часто задаётся с помощью схем JSON Schema, что позволяет точно определить структуру, типы и ограничения данных, которые принимает или возвращает API.

То есть JSON Schema служит языком описания структуры JSON-объектов, а OpenAPI использует эти схемы для формализации контрактов API. Это позволяет автоматически генерировать документацию, валидировать запросы и ответы, а также создавать клиентские и серверные SDK.

Пример фрагмента OpenAPI с описанием JSON-схемы:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
      required:
        - id
        - name