i got this swagger description:
APIExperimentProperties:
type: object
properties:
name:
type: "string"
experimentVariants:
type: array
items:
$ref: "#/definitions/APIExperimentVariantProperties"
owner:
type: "string"
label:
type: "string"
ticketId:
type: "string"
featureName:
type: "string"
APIExperimentVariantProperties:
type: object
required:
- id
- name
properties:
id:
type: "integer"
format: "int64"
name:
type: "string"
I wanted to make the fields id and name in APIExperimentVariantProperties to be marked as required in the swagger-ui.
As you can see in the picture, it looks like it worked.
It removed the optional from the field, and their labels are bolder
(the id field vs the featureName field for example).
But I am trying to make their placeholder say that it's required field, just like it did automatically for the field in the image below.
Any idea how to do that? the decimation didn't give any additional leads.
Related
I have an OpenAPI 3.0.0 spec with a Widget component, which includes an example section:
components:
schemas:
Widget:
properties:
id:
type: string
description:
type: string
cost:
type: float
example:
id: 1234
description: An example widget
cost: 0.10
I'm adding a Warehouse component that includes a list of Widgets. Is there a way to make use of the example on the Widget schema in the Warehouse schema? Something like:
Warehouse:
properties:
id:
type: string
location:
type: string
widgets:
type: array
items:
$ref: '#/components/schemas/Widget'
example:
id: 4321
widgets:
- $ref: '#/components/schemas/Widget'
The above didn't work. I looked at moving the example out of the Widget schema and into a #/components/examples/WidgetExample, but I still wasn't sure what the syntax would look like to refer to that.
The example keyword does not support $ref.
What you can do instead is change the Warehouse schema to use property-level examples for properties other than widgets, in this case the example for widgets will be "inherited" from the Widget schema. At least this is how it works in Swagger UI and Swagger Editor.
Warehouse:
properties:
id:
type: string
example: 4321 # <----
location:
type: string
example: Sample location # <----
widgets:
type: array
items:
$ref: '#/components/schemas/Widget'
Swagger UI will display the following example for Warehouse in the requests and responses:
{
"id": 4321,
"location": "Sample location",
"widgets": [
"id": 1234,
"description": "An example widget",
"cost": 0.1
]
}
There's a year old question with a similar title here, but the
only answer does not answer the question fully so hoping that things
have changed since I'm trying again.
I've a model of a Car which I would like to use with GET requests for creating new instances in which I require to have name.
Additionally, I would like to use this with PUT requests to update an existing instance. Update requests should not have all properties, the Car identifier is already specified in the path and only the present properties would be 'merged' into the existing object.
I tried using the following spec:
CarProperties:
type: object
properties:
name:
type: string
title: Car Name
description: A friendly name for this car.
minLength: 1
md:
type: object
hidden: 'true'
description:
type: string
title: Car Description
description: A detailed description of the car.
md:
type: object
hidden: 'true'
UpdateCar:
allOf:
- { $ref: '#/definitions/CarProperties' }
type: object
NewCar:
allOf:
- { $ref: '#/definitions/CarProperties' }
type: object
required: [name]
I expected having name a required property only in NewCar, however in both NewCar and UpdateCar the property name is optional.
How can I specify a subset of required properties from a referenced model?
After fiddling for a while it seems like I had bad indentation for the required field. The following syntax seems to produce what I wanted:
CarProperties:
type: object
properties:
name:
type: string
title: Car Name
description: A friendly name for this car.
minLength: 1
md:
type: object
hidden: 'true'
description:
type: string
title: Car Description
description: A detailed description of the car.
md:
type: object
hidden: 'true'
UpdateCar:
allOf:
- { $ref: '#/definitions/CarProperties' }
- type: object
NewCar:
allOf:
- { $ref: '#/definitions/CarProperties' }
- type: object
required: [name]
Now I have:
NewCar entity with a required name field.
UpdateCar entity with an optional name field.
If I want to add another property to Car I only need to do it in one place.
Suppose that I have this definition in a yaml OpenApi definition
definitions:
User:
description: "User"
type: "object"
properties:
firstname:
type: "string"
lastname:
type: "string"
password:
type: "string"
email:
type: "string"
username:
type: "string"
If in a parameters specification I need specific fields of a definition how can I refer them without defining another model as below?
definitions:
UserLogin:
description: "User"
type: "object"
properties:
password:
type: "string"
email:
type: "string"
In your question, you are using definitions keyword what hints that your question is about OpenAPI v2 aka. Swagger. For OpenAPI v3, definitions provided below should be defined inside appropriate Components Object sections.
In order to achieve this, you have to use Composition with keyword allOf. There is a great example that relates to your question here. First, you have to define a smaller object and then include it into the definition of a larger as follows:
definitions:
UserLogin:
description: User Login
type: object
properties:
password:
type: string
email:
type: string
User:
allOf:
- $ref: '#/definitions/UserLogin'
- description: User
type: object
properties:
firstname:
type: string
lastname:
type: string
username:
type: string
It is worth noting that:
Some lighter implementations may not support allOf keyword.
Using composition may increase or decrease the readability of the documentation, depending on the complexity and choice of words used to name the schemas.
In my API i would like to have a simple model for my collection and a more elaborate model for my individual resource. For example:
a GET request on /libraries should return
BaseLibrary:
type: object
properties:
library_id:
type: string
description: The id of the library
display_name:
type: string
description: Name of the library
href:
type: string
description: The URI linking to this library.
whilst a request to a specific library should return all of the above including an extra parameter books:
So a GET request to libraries/{library_id} should return:
ExtendedLibrary:
type: object
properties:
library_id:
type: string
description: The id of the library
display_name:
type: string
description: Name of the library
href:
type: string
description: The URI linking to this library.
books:
type: array
description: The books in this library
items:
$ref: "#/definitions/books"
I would very much like to not have to define a "BaseLibrary" twice and would want to simple model an additional "ExtendedLibrary" which contains all the responses of a base library and the additional books property.
I tried a lot of different things, with the closest to succes being the following definitions:
definitions:
BaseLibrary:
type: object
properties:
library_id:
type: string
description: The id of the library.
display_name:
type: string
description: Name of the library
href:
type: string
description: The URI linking to this library.
ExtendedLibrary:
type: object
properties:
$ref: "#/definitions/BaseLibrary/properties"
books:
type: array
description: The available books for this library.
items:
$ref: "#/definitions/Book"
However this gives me a "Extra JSON reference properties will be ignored: books" warning and the output seems to ignore this extra property. Is there a clean way to handle my problem? Or am I just going to have to copy paste my whole BaseLibrary model into my ExtendedLibrary model?
As mentioned in the comments section, this may be a duplicate of another question, but it's worth repeating the answer in the context of this particular example. The solution is to use the allOf property in the definition of ExtendedLibrary:
definitions:
Book:
type: object
properties:
title:
type: string
author:
type: string
BaseLibrary:
type: object
properties:
library_id:
type: string
description: The id of the library
display_name:
type: string
description: Name of the library
href:
type: string
description: The URI linking to this library.
ExtendedLibrary:
type: object
allOf:
- $ref: '#/definitions/BaseLibrary'
- properties:
books:
type: array
description: The books in this library
items:
$ref: "#/definitions/Book"
In my experience, Swagger UI visualizes this correctly. When I define an operation response to be ExtendedLibrary Swagger UI shows this example:
{
"library_id": "string",
"display_name": "string",
"href": "string",
"books": [
{
"title": "string",
"author": "string"
}
]
}
Also, Swagger Codegen does the right thing. At least when generating a Java client, it creates an ExtendedLibrary class that correctly extends BaseLibrary.
I have a series of parameters in Swagger like this
"parameters": [
{
"name": "username",
"description": "Fetch username by username/email",
"required": false,
"type": "string",
"paramType": "query"
},
{
"name": "site",
"description": "Fetch username by site",
"required": false,
"type": "string",
"paramType": "query"
},
{
"name": "survey",
"description": "Fetch username by survey",
"required": false,
"type": "string",
"paramType": "query"
}
],
One parameter MUST be filled out but it doesn't matter which one, the others can be left blank. Is there a way to represent this in Swagger?
Mutually exclusive parameters are possible (sort of) in OpenAPI 3.x:
Define the mutually exclusive parameters as object properties, and use oneOf or maxProperties to limit the object to just 1 property.
Use the parameter serialization method style: form and explode: true, so that the object is serialized as ?propName=value.
An example using the minProperties and maxProperties constraints:
openapi: 3.0.0
...
paths:
/foo:
get:
parameters:
- in: query
name: filter
required: true
style: form
explode: true
schema:
type: object
properties:
username:
type: string
site:
type: string
survey:
type: string
minProperties: 1
maxProperties: 1
additionalProperties: false
Using oneOf:
parameters:
- in: query
name: filter
required: true
style: form
explode: true
schema:
type: object
oneOf:
- properties:
username:
type: string
required: [username]
additionalProperties: false
- properties:
site:
type: string
required: [site]
additionalProperties: false
- properties:
survey:
type: string
required: [survey]
additionalProperties: false
Another version using oneOf:
parameters:
- in: query
name: filter
required: true
style: form
explode: true
schema:
type: object
properties:
username:
type: string
site:
type: string
survey:
type: string
additionalProperties: false
oneOf:
- required: [username]
- required: [site]
- required: [survey]
Note that Swagger UI and Swagger Editor do not support the examples above yet (as of March 2018). This issue seems to cover the parameter rendering part.
There's also an open proposal in the OpenAPI Specification repository to support interdependencies between query parameters so maybe future versions of the Specification will have a better way to define such scenarios.
Unfortunately this isn't possible currently. "required" is just a boolean and there's no way to represent interdependencies between parameters.
Best you can do is make clear the requirements in the parameter descriptions and also put in a custom 400 Bad Request description along the same lines.
There's a bit of discussion at https://github.com/OAI/OpenAPI-Specification/issues/256 about possible ways of implementing this in the next version of the OpenAPI Specification.
What about changing your API design ?
Currently you have one method, 3 parameters. If I understand well, user must always provide exactly one parameter, and two remaining ones must be unset.
For me, API would be more usable with three endpoints -like
/user/byName?name=
/user/bySite?name=
/user/bySurvey?name=
An alternative is to pass in a filter type parameter with an enum, and a filter value with the value to use.
Example at: https://app.swaggerhub.com/api/craig_bayley/PublicAPIDemo/v1
It can be required or not, as you choose. However if one is required, they should both be.