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
Related
I have some schema definitions created with fastify as in below, where I have used 'title' to give meaningful name of my models.
fastify.addSchema({
$id: 'persistence-query-params',
title: "PersistenceQueryParams", // Here
type: 'object',
description: 'Persistence Service GET API URL query specification. Applicable for GET API only.',
properties: {
...........
},
});
However when I am looking at the json generated from the swagger (I am using fastify-swagger: 4.8.4 and fastify: 3.20.1), I am seeing this
def-7: ## Here
title: PersistenceQueryParams
type: object
description: >-
Persistence Service GET API URL query specification. Applicable for GET
API only.
properties:
This is coming up in the OpenAPI 2.0 https://editor.swagger.io/, when loading the json generated out of that schema.
I have tried out adding the name field also:
name: "PersistenceQueryParams",
However no luck.
How can I create meaningful names, instead of def-0, def-1 etc in OpenAPI 2.0?
Thanks,
Pradip
The OpenAPI 3.0 docs about apiKey security have left me confused about the use of a field in the 'security' component of the specification. What is the purpose of the array value on the field that points to one of the defined securitySchemes.
Place holder keys? Nothing?
openapi: 3.0.0
...
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
security:
- ApiKeyAuth: [] <-- What's the array for?
This array contains a list of required scopes, but the "API key" security scheme does not use scopes. Scopes are only used with OAuth 2.0 and OpenID Connect security schemes. There's an enhancement request to allow scopes for API keys too.
I am currently working on project using Symfony 4.3.4 and API platform v2.3.6.
I am facing 1 issue right now. Let’s say I send a GET request to an enpoint with a query string parameter called products because I send 1 or more product IDs.
I want to get the value of the products parameter in my controller as a PHP array.
So my request is
GET /my/endpoint?products[]=8f391c60-5467-4bf0-917f-e2151337fa7e&products[]=ddaa94e1-af79-4abf-9dfc-a28dd8077f45
In the controller I perform a dump:
dump($request->query->get("products"));
Then I get:
array:2 [
0 => "8f391c60-5467-4bf0-917f-e2151337fa7e"
1 => "ddaa94e1-af79-4abf-9dfc-a28dd8077f45"
]
As you can see the way I pass my product IDs like an array in the query string, I can retrieve the products parameter as a PHP array.
My concern here, is the swagger documentation.
Using this configuration in YAML:
collectionOperations:
operation_name:
method: get
path: /my/endpoint
controller: App\Controller\MyEndpointController
swagger_context:
summary: My summary
description:
My endpoint description
responses:
parameters:
-
in: query
name: products
description: "The products IDs parameter"
schema:
type: array
items:
type: "string"
example: "019fcd9b-beea-4791-8a59-d4e2d02427d6"
In the API documentation page when I choose Try it out I have to fill in all the parameters value included products. The problem is that products parameter appears as a text input.
If I remove the schema key in the yaml configuration of the parameter and I put type: array and items keys directly at the same level as in, name and description:
parameters:
-
in: query
name: products
description: "The products IDs parameter"
type: array
items:
type: "string"
example: "019fcd9b-beea-4791-8a59-d4e2d02427d6"
Then the products parameter appears with a button Add item. Each time I click on this button, I can fill a product ID to pass and that is fine. The problem is that when I click on Execute (still in the API documentation page) I have an error because API platform does not send the request with products parameter as a true array but as a string containing all product IDs separated by ,:
GET /my/endpoint?products=8f391c60-5467-4bf0-917f-e2151337fa7e,ddaa94e1-af79-4abf-9dfc-a28dd8077f45
and this is what I want:
GET /my/endpoint?products[]=8f391c60-5467-4bf0-917f-e2151337fa7e&products[]=ddaa94e1-af79-4abf-9dfc-a28dd8077f45
any idea about the way to achieve this with API platform?
The query parameter needs to be named products[] (with square brackets) and have the collectionFormat: multi attribute:
parameters:
- in: query
name: products[]
type: array
items:
type: string
format: uuid
collectionFormat: multi
# (Optional) Array example to display in Swagger UI
x-example:
- 8f391c60-5467-4bf0-917f-e2151337fa7e
- ddaa94e1-af79-4abf-9dfc-a28dd8077f45
Note that query parameters in OpenAPI 2.0 do not support the example keyword, but some tools (such as Swagger UI) support the x-example extension to specify the example values for query parameters.
Learning about REST APIs and am following https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-2-the-basics/.
The API can receive two parameters: username and bla, but only username is required by using the required keyword. This makes sense to me.
The API will return firstname, lastname, and username, but only username is required by using the required keyword. This does not make sense to me. Does the lack of the required keyword indicate that the other two might sometimes not be required? What influences whether they are or are not?
paths:
/persons/{username}:
get:
summary: Gets a person
description: Returns a single person for its username.
parameters:
- name: username
in: path
required: true
description: The person's username
type: string
- name: bla
in: query
description: bla bla bla
type: string
responses:
200:
description: A Person
schema:
required:
- username
properties:
firstName:
type: string
lastName:
type: string
username:
type: string
404:
description: The Person does not exists.
Your interpretation is correct. If a property of a response object is listed in the required property list, is must be present in the response object for it to be valid, quite similar to the required field in a parameter object. Whether a non-required property is included in the response or not is up to the business logic of your application to decide.
Some more information with pointers to the relevant parts of the specification below:
The semantics of the required property list of a response object is defined as part of the Schema Object section of the OpenAPI specification. There it says that the schema object "is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it".
In the corresponding section on the required validation keyword of the JSON Schema Validation specification its semantics is defined as follows:
5.4.3. required
5.4.3.1. Valid values
The value of this keyword MUST be an array. This array MUST have at
least one element. Elements of this array MUST be strings, and MUST be
unique.
5.4.3.2. Conditions for successful validation
An object instance is valid against this keyword if its property set
contains all elements in this keyword's array value.
You'll find further examples of how the required keyword can be used in the examples section of the JSON Schema specification or Part 5, Section 2.2 of the tutorial you're following.
I have an endpoint to create an address and one to update it. Describing this in an OpenAPI spec I'd like to use a component for the address so that I don't have to specify the address twice. Now the problem is, that the address object used for updating should include a property "id", but the one used for creating doesn't.
So basically, I'm looking for a way to describe the full address (incl. the id property) in the components section and then reference to the create endpoint, but excluding the "id" property there.
You can extend another type using the allOf keyword, as documented here
In the example below, creationType has only a name property, but updateType has all the properties of creationType as well as an id property.
Example:
components:
schemas:
creationType:
type: object
properties:
name:
type: string
updateType:
allOf:
- $ref: '#/components/schemas/creationType'
- type: object
required:
- id
properties:
id:
type: string