I have this structure in swagger documentation:
FunctionTitle:
type: object
required:
- funcId
- czechName
- priority
properties:
funcId:
type: number
format: id
example: 1226
czechName:
type: string
example: Guvernér
priority:
type: number
example: 21
org:
$ref: '#/definitions/Organ'
funcType:
$ref: '#/definitions/FunctionType'
In some path I want to return this structure, but without properties org and funcType. So my response should be something like that:
{
"funcId" : 1226,
"czechName" : "Guvernér",
priority: 21
}
I didnt find how to choose not to return properties org and funcType. I know I can create another model for it, but it will be better for me to only hide properties as I want and not to create another model. Here is example of my path:
/periods:
get:
tags:
- developers & users
summary: Periods
operationId: periods
description: |
By passing in the appropriate options, you can search for
available inventory in the system
produces:
- application/json
responses:
200:
description: search matching criteria
schema:
type: object
properties:
periods:
type: array
items:
$ref: '#/definitions/FunctionTitle'
400:
description: bad input parameter
Thank you for your answers!
Related
I am writing API documentation using OpenAPI 3.0. At the moment I have:
paths:
/script/update:
post:
tags:
- "Script"
summary: Update a script
operationId: updateScript
responses:
'200':
description: OK
"404":
description: Not Found
requestBody:
description: A script object in order to make the request
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
subsite_id:
type: string
script:
type: object
properties:
script:
$ref: '#/components/schemas/ScriptType'
type:
type: string
enum:
- custom
- interface
- freshbot
- feeder
- getter
- smcf
status:
$ref: '#/components/schemas/ScriptStatus'
comment:
type: string
format: string
reason:
type: string
format: string
To problem comes when I try to use to Swagger UI.
The only thing that appears is the following:
What I want is that the script object can be filled out field by field for each of the properties it has, like the subsite_id. What am I missing?
Swagger UI 3.x and 4.x do not have a form editor for JSON objects, so all JSON data needs to be entered in the JSON format: { "prop": value, ... }
Here's the corresponding feature request you can track:
https://github.com/swagger-api/swagger-ui/issues/2771
I have a model defined as:
Event:
type: object
properties:
id:
type: string
timestamp:
type: string
format: date-time
type:
type: string
enum:
- click
- open
- sent
click:
type: object
properties:
url:
type: string
title:
type: string
open:
type: object
properties:
subject:
type: string
sent:
type: object
properties:
subject:
type: string
from:
type: string
to:
type: string
However, the shape is actually different depending on the value of the type enum field. It can be one of three, I tried to define the differences in the examples (see below) but this did not work.
As you can see, the below shows three examples, each one is different depending on the type. This is how the API behaves, but it is not straightforward to document this expected behaviour.
examples:
application/json:
- id: >
ad1b12f0-63a8-47b5-9820-3e447143ce7e
timestamp: >
2017-09-29T16:45:20.000+00:00
type: click
click:
url: >
www.some-website-somewhere.org/12345
title: >
Click here!
- id: >
d9e787fa-db49-4bd8-97c3-df45f159295c
timestamp: >
2017-09-29T16:45:20.000+00:00
type: open
open:
subject: >
Have you seen this?
- id: >
30adc194-0f5f-4889-abd4-4fa964d0bb42
timestamp: >
2017-09-29T16:45:20.000+00:00
type: sent
sent:
subject: >
Have you seen this?
from: >
bill#office.gov
to: >
mon#gmail.com
I read a few places that mention this is not possible, but I am hoping to get some "outside the box" thinkers to help me find a solution.
This is possible using model inheritance/composition and discriminator.
First, define the base model Event that contains just the common properties, and mark the type property as discriminator:
definitions:
Event:
type: object
discriminator: type
required:
- type # discriminator property is required
properties:
id:
type: string
example: ad1b12f0-63a8-47b5-9820-3e447143ce7e
timestamp:
type: string
format: date-time
example: 2017-09-29T16:45:20.000+00:00
type:
type: string
enum:
- click
- open
- sent
Then inherit the click/open/sent models from the base Event model via allOf. The names of the child models must be the same as the values of the discriminator property. In your example, the models must be named click, open and sent. If you use Swagger UI, you can add title to override the displayed model names.
click:
title: ClickEvent
allOf:
- $ref: '#/definitions/Event'
- type: object
properties:
click:
type: object
properties:
url:
type: string
example: www.some-website-somewhere.org/12345
title:
type: string
example: Click here!
In operations, use the base model (Event) as the request or response schema:
responses:
200:
description: OK
schema:
$ref: '#/definitions/Event'
The clients should examine the value of the discriminator property (in this example - type) to decide which inherited model to use.
Note for Swagger UI users: Swagger UI and Swagger Editor currently do not support switching models based on discriminator. Follow this issue for updates.
In OpenAPI 3.0 it's easier - you can simply use oneOf to define alternate schemas for a request or response.
responses:
'200':
description: OK
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ClickEvent'
- $ref: '#/components/schemas/OpenEvent'
- $ref: '#/components/schemas/SentEvent'
# Optional mapping of `type` values to models
discriminator:
propertyName: type
mapping:
click: '#/components/schemas/ClickEvent'
open: '#/components/schemas/OpenEvent'
sent: '#/components/schemas/SentEvent'
Is it possible to group multiple parameters to reference them in multiple routes?
For example I have a combination of parameters which I need in every route. They are defined as global parameters. How can I group them?
I think about a definition like this:
parameters:
MetaDataParameters:
# Meta Data Properties
- name: id
in: query
description: Entry identification number
required: false
type: integer
- name: time_start
in: query
description: Start time of flare
required: false
type: string
- name: nar
in: query
description: Active region number
required: false
type: string
And then reference the whole group in my route:
/test/:
get:
tags:
- TEST
operationId: routes.test
parameters:
- $ref: "#/parameters/MetaDataParameters"
responses:
200:
description: OK
Is this possible with Swagger 2.0?
This is not possible with Swagger 2.0, OpenAPI 3.0 or 3.1. I've opened a feature request for this and it is proposed for a future version:
https://github.com/OAI/OpenAPI-Specification/issues/445
you can point your $ref to middle .yaml file, like this:
//middle.yaml <-----
- $ref: 'Defaul.yaml#/components/parameters/meta_id'
- $ref: 'Defaul.yaml#/components/parameters/meta_time_start'
- $ref: 'Default.yaml#/components/parameters/meta_nar'
your Default.yaml file should be like this:
//Default.yaml <-----
components:
parameters:
meta_id:
name: id
in: query
description: Entry identification number
schema:
type: integer
example: 1
meta_time_start:
name: time_start
in: query
schema:
type: string
finally, your main file should be looks like this:
/test/:
get:
tags:
- TEST
operationId: routes.test
parameters:
$ref: "../parameters/middle.yaml" <---- external yaml file
responses:
200:
description: OK
NOTE: your $ref should be without -. like in my example
I have a service that can have two different kind of body parameters based on the Content-Type header.
E.g. for path /Pet:
If Content-Type: application/somecustom.resource+json is used, then POST can take up Pet as the body parameter.
If Content-Type: application/somecustom.function+json is used, then POST should take up some different body parameter to invoke a function and return a different response.
Any suggestion on how to manifest this in OpenAPI (Swagger)?
OpenAPI 3.0 supports different schemas per media type.
openapi: 3.0.0
...
paths:
/pet:
post:
requestBody:
required: true
content:
application/somecustom.resource+json:
schema:
$ref: '#/components/schemas/Pet'
application/somecustom.function+json:
schema:
$ref: '#/components/schemas/Foo'
No, it's not possible to define a two different body parameters for the same operation, in the same path item. The path item name are unique by virtue of being property names (and therefore "keys" in the JSON key-value map), and Swagger specification allows at most one body parameter in a given operation.
There are a few alternative approaches to address this need:
Create two separate path items
For example:
/pets/createFromDescription:
post:
summary: Create a pet from a basic description
operationId: createPetFromDescription
parameters:
- name: petDescription
in: body
required: true
schema:
$ref: "#/definitions/PetDescriptionObject"
responses:
200:
description: OK
/pets/createFromCatalog:
post:
summary: Create a pet from a standard catalog entry
operationId: createPetFromCatalogEntry
parameters:
- name: petCatalogEntry
in: body
required: true
schema:
$ref: "#/definitions/PetCatalogEntry"
responses:
200:
description: OK
Create subtypes, with a discriminator
Described in the Swagger–OpenAPI 2.0 specification here.
Example:
/pets:
post:
summary: Create a pet
operationId: createPet
parameters:
- name: petSource
in: body
description: Structured pet information, from which to create the object
required: true
schema:
$ref: "#/definitions/CreatePet_Request"
responses:
200:
description: OK
definitions:
CreatePet_Request:
type: object
properties:
requestVariant:
type: string
required:
- requestVariant
discriminator: requestVariant
PetDescriptionObject:
allOf:
- $ref: "#/definitions/CreatePet_Request"
- type: object
properties:
name:
type: string
description:
type: string
PetCatalogEntry:
allOf:
- $ref: "#/definitions/CreatePet_Request"
- type: object
properties:
SKU:
type: string
Breed:
type: string
Comments:
type: string
Neither of these methods is keyed to the media type of the request. While your request may accept multiple media types, if the use of a particular media type implies some requirement about the request body, you'd have to document that in the description property of the operation or body parameter.
Is it possible to group multiple parameters to reference them in multiple routes?
For example I have a combination of parameters which I need in every route. They are defined as global parameters. How can I group them?
I think about a definition like this:
parameters:
MetaDataParameters:
# Meta Data Properties
- name: id
in: query
description: Entry identification number
required: false
type: integer
- name: time_start
in: query
description: Start time of flare
required: false
type: string
- name: nar
in: query
description: Active region number
required: false
type: string
And then reference the whole group in my route:
/test/:
get:
tags:
- TEST
operationId: routes.test
parameters:
- $ref: "#/parameters/MetaDataParameters"
responses:
200:
description: OK
Is this possible with Swagger 2.0?
This is not possible with Swagger 2.0, OpenAPI 3.0 or 3.1. I've opened a feature request for this and it is proposed for a future version:
https://github.com/OAI/OpenAPI-Specification/issues/445
you can point your $ref to middle .yaml file, like this:
//middle.yaml <-----
- $ref: 'Defaul.yaml#/components/parameters/meta_id'
- $ref: 'Defaul.yaml#/components/parameters/meta_time_start'
- $ref: 'Default.yaml#/components/parameters/meta_nar'
your Default.yaml file should be like this:
//Default.yaml <-----
components:
parameters:
meta_id:
name: id
in: query
description: Entry identification number
schema:
type: integer
example: 1
meta_time_start:
name: time_start
in: query
schema:
type: string
finally, your main file should be looks like this:
/test/:
get:
tags:
- TEST
operationId: routes.test
parameters:
$ref: "../parameters/middle.yaml" <---- external yaml file
responses:
200:
description: OK
NOTE: your $ref should be without -. like in my example