Now that we have learned how to use Components to reduce code duplication, let's carry on with specifying the Get User endpoint, and learn how to represent URL parameters in OpenAPI.
It turns out that it's very simple—it's just another parameter, just like query parameters. The only difference is that we need to use path templating to specify where this parameter resides in our URL. For instance, the path would be specified as /users/{userId} for our Retrieve User endpoint.
We also need to define a new Schema object called UserLimited, which describes a complete User object but without the digest field. This is the shape of the object we will return in our Retrieve User endpoint. Lastly, we also added a new ErrorNotFound response to cater for when a user with that ID does not exist.
The additions made to the schema should resemble the following:
...
components:
schemas:
...
UserLimited:
title: Retrieve User Response Payload Schema
description: An User object with the digest field removed
properties:
email:
type: string
format: email
profile:
$ref: '#/components/schemas/Profile'
additionalProperties: false
required:
- profile
...
responses:
...
UserRetrieved:
description: User Retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/UserLimited'
...
ErrorNotFound:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
paths:
...
/users/{userId}:
get:
tags:
- Users
summary: Retrieves details of a single User
parameters:
- name: userId
in: path
description: ID of the User to retrieve
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/UserRetrieved'
'400':
$ref: '#/components/responses/ErrorBadRequest'
'404':
$ref: '#/components/responses/ErrorNotFound'
'500':
$ref: '#/components/responses/ErrorInternalServer'