I am struggling to find an example code that has implemented and is using open api v3 links. How should the response look like coming from the backend, that has links described in open api, so that it would comply with the documentation?
Let's take an example from docs:
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
How response after POST should look like? Should it include nested object with direct links
to that created user? Or should it only include id and client should figure out how to call that GetUserByUserId operation?
Basically, how should backend provide those links, described in openapi, so that client could use them? Is there any standard how to do it, or does it come down to personal preference?