I’m using Openapi 3.0 and I am trying to create a query parameter that is required for one endpoint and optional for another. Since parameters are now defined using schemas, I don’t know if this is possible.
Yes it's possible - both in OpenAPI 3.0 and 2.0. In the context of parameters, the required attribute is a parameter-level attribute, not a schema attribute.
paths:
/something:
get:
parameters:
- in: query
name: foo
required: true # <-----
schema:
type: string
...
/something-else:
get:
parameters:
- in: query
name: foo
required: false # <----- Can be omitted because parameters are optional by default
schema:
type: string
...
Related
I have this api documentation written in OpenAPI 3.0.3
openapi: 3.0.3
info:
version: '1.0'
title: 'MyTitle'
description: Specification for Bear Store
servers:
- url: https://development.example.com/v1
description: Development Server
paths:
'/v1/bears':
get:
description: Requests a lists all the bears
summary: List of bears request
responses:
'200':
description: List of Bears
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
I have a Bear object that has id, and name properties. I want to define that id field is a unique field. How can I define this in OpenAPI 3?
OpenAPI lets you define a field's type and its expected format. But it's not possible for it to ensure its uniqueness.
Uniqueness is a business concern, which might involve non-trivial checks. Therefore, it's outside the scope of OpenAPI/Swagger to formalize such concepts.
However, you can add a description to explain the requirement that the field value must be unique, then implement necessary checks in the API to ensure that the value supplied by the client is actually unique.
I am trying to document the response for an endpoint that accepts multiple mime type requests and returns a different response based on the type. One response type, pdf, returns its own schema separate from the others. The rest all return the same schema and same example. This syntax works. Almost. Except in the UI example, the JSON response is also showing the string "$ref: example-two.json" along with the appropriate response example. Like:
{
"key": "value",
"key2": "value2",
"$$ref: example-two.json"
}
when it should just be:
{
"key": "value",
"key2": "value2"
}
I've been scouring the docs and stack and google and I don't see any examples of making something like this work. Or rather, I'm not seeing why this one isn't working, but I haven't seen any examples that include $refs for each example.
responses:
200:
content:
application/pdf:
schema:
$ref: ../app.yaml#/components/schemas/ModelOne
application/json:
schema:
$ref: ../app.yaml#/components/schemas/ModelTwo
examples:
Example:
value:
$ref: example-two.json
text/html:
schema:
$ref: ../app.yaml#/components/schemas/ModelTwo
examples:
Example:
value:
$ref: example-two.json
For context - I cannot change the endpoint behavior and I do need to show an example for each mime type even if they are the same. Because the one is different. Thank you in advance!
There are two ways to $ref an example in OpenAPI 3.0:
1) Define the example in the components/examples section. In this case the $ref is used inside the examples.<name> key (not inside value).
examples:
Example:
$ref: '#/components/examples/MyExample'
...
components:
examples:
MyExample:
summary: Optional short description of this example
value:
key: value
key2: value2
2) If the example-two.json file contains just the example value (in this case - sample JSON), you can use externalValue to link to that file:
examples:
Example:
externalValue: example-two.json
Notes:
Relative URLs in externalValue are resolved against the API server URL (servers[*].url) and not the location of the OpenAPI definition file. You may need to use an absolute URL.
Examples with externalValue are currently (as of December 2019) not displayed in Swagger UI - see issue #5433.
This question already has answers here:
Re-using model with different required properties
(2 answers)
Closed 3 years ago.
This is my code:
definitions:
User:
type: object
properties:
id:
type: integer
username:
type: string
first_name:
type: string
last_name:
type: string
password:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- username
- first_name
- last_name
- password
/api/users:
post:
description: Add a new user
operationId: store
parameters:
- name: user
description: User object
in: body
required: true
type: string
schema:
$ref: '#/definitions/User'
produces:
- application/json
responses:
"200":
description: Success
properties:
success:
type: boolean
data:
$ref: '#/definitions/User'
As you can see, in the post key under /api/users I used the User definition as my schema on it.
I want to lessen my code so I reused the User definition as my schema. The problem here is that I do not need the id, created_at and updated_at fields.
Is there a way to just inherit some of the fields except the fields mentioned? Also, I would love some suggestions to make it better since I'm trying to learn swagger. Thank you.
As explained in this answer to a similar question:
You would have to define the models separately.
However, you have options for the cases of exclusion and difference.
If you're looking to exclude, which is the easy case, create a model
of with the excluded property, say ModelA. Then define ModelB as
ModelA plus the additional property:
ModelB:
allOf:
- $ref: "#/definitions/ModelA"
- type: object
properties:
id:
type: string
If you're looking to define the difference, follow the same method
above, and exclude the id from ModelA. Then define ModelB and ModelC
as extending ModelA and add the id property to them, each with its own
restrictions. Mind you, JSON Schema can allow you to follow the
original example above for some cases to "override" a definition.
However, since it is not really overriding, and one needs to
understand the concepts of JSON Schema better to not make simple
mistakes, I'd recommend going this path for now.
Is there a way to exclude one or more properties from a request body when you use a type and writing your API using RAML 1.0
I'll explain. I have a type: 'Order' with a set of properties. I have a resource /orders and a method post which allows users to create a new order.
The request body is an order struct json and a response is an order struct as well.
But I don't want users to specify order id while they are submitting their request. But that id (and a couple more 'response only' fields) will be returned at the response. I don't want to create an extra type, like OrderRequest and then inherit it with an Order type, maybe there is a more elegant solution?
So I want to have a way to exclude some properties from a request body and keep others in order to use their description and examples.
Thanks and sorry for my English :)
Use two types. The second will be child of the first. Example:
#%RAML 1.0
title: GitHub API
version: v3
baseUri: https://api.github.com
mediaType: application/json
types:
OrderCreating:
type: object
properties:
products:
description: List of product ids with amount.
required: true
type: object
properties:
[]:
type: number
coupon?: string
Order:
type: OrderCreating
properties:
id: integer
price: number
...
/orders:
post:
body:
application/json:
type: OrderCreating
/{orderId}:
get:
responses:
200:
body:
application/json:
type: Order
Also you can include Library with declaration of your types.
As you don't want to create an extra type with inheritance you can still mark the field as optional and document that it is present in the response.
I am writing my first Swagger spec for a search endpoint and wondering if there is a simple way to negate a search parameter.
Here is the yml for searching by brand:
properties:
brand:
description: The magazine that produced the original article
type: string
I would also like our users to be able to search by excluding a brand (eg either "from [brand]" or "not from [brand]". Is there a more graceful approach than creating duplicate properties for each parameter (eg, both brand and notBrand)?
I'd suggest the following. If you are using query parameters for the search endpoint (which is probably smart), you should consider having a querystring parameter like such:
- name: brand
in: query
type: array
items:
type: string
You can have another query parameter for excludes which follows the same syntax. Be sure to set the collectionFormat depending on how your API will parse the query string, since arrays are simply not standardized across frameworks. Read here for more details.