Using OpenAPI 3+ and Redoc, and having issues with references not working once I go more than one level deep, is there something i'm doing wrong or missing here?
openapi.yaml
components:
schemas:
$ref: components/schemas/_index.yaml
components/schemas/_index.yaml
AdminParticipants:
$ref: ./admin/Participants.yaml
admin:
$ref: "./admin/_index.yaml"
components/schemas/admin/_index.yaml
Participants:
$ref: ./Participants.yaml
When trying to access the schema model using below reference it does not work (get Invalid reference token: Participants error)
$ref: "#/components/schemas/admin/Participants"
However this does work:
$ref: "#/components/schemas/AdminParticipants"
Is it not possible to create nested references more than one level deep for schemas or any other components?
OpenAPI does not actually support $ref directly under the components.schemas node. You can only $ref individual schemas or schema properties. Some tools might accept $refs in arbitrary places, but the behavior may vary.
Here's the version that will work with any OpenAPI-compliant tools:
# openapi.yaml
components:
schemas:
AdminParticipants:
$ref: ./admin/Participants.yaml
AnotherSchema:
$ref: ./path/to/schema.yaml
You'll can then reference these schemas as:
$ref: '#/components/schemas/AdminParticipants'
$ref: '#/components/schemas/AnotherSchema'
The following will NOT work - not only because of non-standard $ref placement in openapi.yaml, but also because it would result in a wrong structure of the schemas section.
# openapi.yaml
components:
schemas:
$ref: components/schemas/_index.yaml
# components/schemas/_index.yaml
admin:
$ref: "./admin/_index.yaml"
# components/schemas/admin/_index.yaml
Participants:
$ref: ./Participants.yaml
After dereferencing, the snippets above become:
components:
schemas:
admin:
Participants:
type: object # or however the schema is defined in 'Participants.yaml'
...
which has an extra key between the schema name and schema contents, so it's not valid OpenAPI.
Related
I can get the openapi3 operation model as described in the documentation,
but I would like to get the referenced schema properties.
for example I have the "post-example" operation in my yaml:
/post-example:
post:
summary: Example for all the possible 200 query responses
operationId: post-example
tags:
- read
requestBody:
required: true
content:
"application/json":
schema:
$ref: "#/components/schemas/example-query"
responses:
200:
description: Expected response to a valid request
and I would like to get the "example-query" schema properties.
Is this possible with vertx 4.0.0?
Using RouterBuilder#getOpenAPI() you can get the OpenAPIHolder, which allows you to access to any component of the OpenAPI document using JsonPointer:
OpenAPIHolder holder = routerBuilder.getOpenAPI();
Object schema = holder.getCached(
JsonPointer.from("#/components/schemas/example-query")
);
I am using OpenAPI 3.0 to design and implement a simple API to allow basic CRUD operations on database entities.
Let's assume an entity Pet with some client-given properties (name & age) and some generated properties (id & created):
components:
schemas:
Pet:
type: object
properties:
id:
type: string
created:
type: string
format: date-time
name:
type: string
age:
type: integer
I want to specify REST endpoints to POST, GET, PUT (and if possible PATCH) a pet:
paths:
/pets:
post:
operationId: createPet
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
responses:
"200":
content:
application/json:
schema:
type: boolean
/pets/{id}:
parameters:
- name: id
schema:
type: string
in: path
required: true
get:
operationId: getPet
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
put:
operationId: updatePet
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
responses:
"200":
content:
application/json:
schema:
type: boolean
patch:
operationId: alterPet
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
responses:
"200":
content:
application/json:
schema:
type: boolean
From a logical point of view, the following properties are required per endpoint:
GET: id, created, name, age
POST: name, age
PUT: name, age
PATCH: name or age (or none depending on implementation)
I see two major approaches here:
Approach 1: Leave all properties optional
The Pet DTO is used as a shell where all properties are optional as defined above. It is left to the server & client to check if the required properties are filled on an endpoint call. If non-required properties are set in a POST/PUT/PATCH request body, they will be ignored.
pros:
Single, simple, and symmetric DTO schema definition in the API specification.
Smooth integration of the "GET -> modify -> PUT" workflow on the client side (e.g., a React frontend with Formik).
Supports the PATCH endpoint out-of-the-box.
cons:
All properties are optional and it is very tedious to handle these string | undefined types in Typescript. This is especially annoying in the GET direction as we know that all properties will be filled as long as we retrieve the Pet DTO.
The implementational "pain" is spread over the server and all possible clients.
Approach 2: Define separate DTO schemas for all operations
We introduce a GetPet, PutPet, PostPet, and PatchPet with corresponging required lists in the API specification. Yes, PutPet and PostPet can be identical, but maybe we want to allow a modified GetPet to be used as PutPet to streamline the "GET -> modify -> PUT" workflow for the client.
Imagine the Pet entity having 5+ generated properties and 20+ client-given properties. We do not want to flat define 4 variations of each entity, but use some kind of inheritance instead. Is there a way to introduce a BasePet bearing all properties (set to optional) and let the 4 operation-specific DTOs extend it with just overriding the required list?
pros:
Easier implementation for client & server as optionality is clarified for all properties.
The "pain" is handled in the API specification.
cons:
The API specification grows in complexity. It is not clear to me if the desired inhertance is possible and how it is specified.
Scalability & maintainability of the API may suffer.
So my question on this topic: How can the inhertiance of the DTOs be specified for OpenAPI 3.0? Are there better alternatives? I am happy for all suggestions concerning these thoughts on an API for basic CRUD operations.
I did face a similar issue while designing an API for a client recently. The trick here is to $ref: redundancies in the schemata for the different routes. For simplicity, I will only define GET, POST and PATCH.
Note: In this case it is easier, as the schema for write operations is a subset of the schema for the read operation.
By contrast, imagine a user-object, where there is a password field, it should be writable, but not readable. In this case, you would need three different schemata:
userRead
userWrite
userCommonFieldsForReadAndWrite
In any case, here is one possible solution to your question:
paths:
/pets:
post:
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/petCreateUpdate"
responses:
"201":
description: Pet created.
headers:
Location:
schema:
type: string
description: points to the Pet resource created. Can be directly used in a subsequent GET request.
example: "Location: /pets/32"
/pets/{id}:
parameters:
- name: id
schema:
type: string
in: path
required: true
get:
responses:
"200":
description: Pet with given id returned.
content:
application/json:
schema:
$ref: "#/components/schemas/petRead"
"404":
description: Pet with given id not found.
patch:
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/petCreateUpdate"
responses:
"204":
description: Pet updated successfully.
components:
schemas:
petRead:
allOf:
- type: object
properties:
id:
type: integer
format: int32
minimum: 1
created:
type: string
format: date-time
- $ref: "#/components/schemas/petCreateUpdate"
petCreateUpdate:
type: object
properties:
name:
type: string
age:
type: number
format: integer
minimum: 1
maximum: 100
This renders in SwaggerEditor as follows:
POST for the Pet
GET for the Pet
PATCH for the Pet
I want a field in a PUT body that is itself supposed to be a jsonschema. How do I formally specify this rather than putting that info in a description?
type: object
description: "..."
properties:
foo:
type: integer
create_schema:
type: object
description: >
jsonschema (following http://json-schema.org/draft-07/schema) of the CREATE payload...
OpenAPI doesn't like the schema keyword in a definition here
I am consuming an API that uses string like "foo/bar" to identify (discriminate) JSON objects.
A $ref like $ref: '#/components/schemas/foo/bar' gives me errors.
Is this naming supported? I want to use leverage these properties provided by the API in order to use discrimination to pick the most appropriate component schema.
I am using OpenAPI 3.0.1.
No.
OpenAPI 3.0 component names (including schema names) can only contain these characters:
a-z A-Z 0-9 - . _
(Source)
However, there are no restrictions on property names in schemas, so / can be used in property names:
components:
schemas:
MySchema:
type: object
properties:
foo/bar: # <-----
type: string
What I'd like to do is specify that sometimes the response to an API call might be a PDF document, and sometimes it will be JSON. I'd like to do this in OpenAPI 3.0 format. In the case of a PDF, the response would look like this:
responses:
'200':
description: An invoice in PDF format.
content:
application/pdf:
schema:
type: string
format: binary
And in the case of a JSON response, this would describe the response:
responses:
'200':
description: A JSON object containing user name and avatar
content:
application/json:
schema:
$ref: "#/components/schemas/Invoice"
The OAS3 documentation (https://swagger.io/docs/specification/describing-responses/) provides the following example for how to specify that one of a few different JSON schemas could be the response to a particular API call. This is almost what I want, except instead of describing different possible JSON schemas, I'd like to specify different possible content types, as described above. Is there a way to do this in OAS3 format?
responses:
'200':
description: A JSON object containing pet information
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Hamster'
Just found that this works:
responses:
'200':
description: "An invoice."
content:
application/json:
schema:
$ref: "#/components/schemas/Invoice"
application/pdf:
schema:
type: "string"
format: "binary"
See the "Response Media Types" section here: https://swagger.io/docs/specification/describing-responses/