Как должны быть открыты ссылки api v3.0.0, реализованные в бэкэнде - PullRequest
Новая
       22

Как должны быть открыты ссылки api v3.0.0, реализованные в бэкэнде

1 голос
/ 06 мая 2020

Я изо всех сил пытаюсь найти пример кода, который реализовал и использует открытые ссылки api v3. Как должен выглядеть ответ, исходящий от бэкэнда, ссылки на который описаны в открытом API, чтобы он соответствовал документации?

Возьмем пример из документации: 

openapi: 3.0.0
info:
  version: 0.0.0
  title: Links example
paths:
  /users:
    post:
      summary: Creates a user and returns the user ID
      operationId: createUser
      requestBody:
        required: true
        description: A JSON object that contains the user name and age.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                    description: ID of the created user.
          # -----------------------------------------------------
          # Links
          # -----------------------------------------------------
          links:
            GetUserByUserId:   # <---- arbitrary name for the link
              operationId: getUser
              # or
              # operationRef: '#/paths/~1users~1{userId}/get'
              parameters:
                userId: '$response.body#/id'
              description: >
                The `id` value returned in the response can be used as
                the `userId` parameter in `GET /users/{userId}`.
          # -----------------------------------------------------
  /users/{userId}:
    get:
      summary: Gets a user by ID
      operationId: getUser
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: A User object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
        name:
          type: string

Как должен выглядеть ответ после POST? Должен ли он включать вложенный объект с прямыми ссылками на созданного пользователя? Или он должен включать только идентификатор, и клиент должен выяснить, как вызвать эту операцию GetUserByUserId?

В принципе, как бэкэнд должен предоставлять эти ссылки, описанные в openapi, чтобы клиент мог их использовать? Есть ли какие-то стандарты, как это сделать, или это зависит от личных предпочтений?

...