openapi: "3.0.0"
info:
title: project
servers:
- url: http://example1.net/v3
- url: http://example/v3
paths:
/Pn/{PnId}/service1:
post:
summary: Pn data
description: |
can Pn the data
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/dataInfo"
application/x-www-form-urlencoded:
schema:
$ref: "#/components/schemas/dataInfo"
parameters:
- name: PnId
in: path
description: PnId
required: true
schema:
$ref: "#/components/schemas/Pn"
responses:
'200':
description: status
content:
application/json:
schema:
$ref: "#/components/schemas/dataInfoStatus"
example: infoable
default:
description: error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
schemas:
Error:
type: object
properties:
code:
type: integer
message:
type: string
required:
- message
Pn:
type: integer
format: int64
dataInfo:
type: string
dataInfoStatus:
type: string
enum: [infoable, non_infoable,ignorable]
I am sending a single dataInfo in request and getting single dataInfoStatus in response, but I will like to send and array of dataInfo and get an array of dataInfo status.
I tried following:
schema:
type:array
items:
$ref: "#/components/schemas/dataInfo"
but I get
Parser error bad indentation of a mapping entry
for items. I am following this.
How can I achieve sending dataInfo in request as an array of dataInfo and getting in response an array of dataInfoStatus?
You have to add one more space between type: and array, then the error message is gone:
schema:
type: array
items:
$ref: "#/components/schemas/dataInfo"
And you can add the info.version for the version of the openapi file.
Related
Swagger - Tried to Add Header from Componenet
paths:
'/customer':
post:
tags:
- Customer
summary: Create Customer
description: Create Customer
operationId: createCustomer
parameters:
- in: header
name: operationId
description: Content Type
required: true
schema:
type: string
example: createCustomer
- $ref: '#/components/parameters/clientId'
- $ref: '#/components/parameters/tenantId'
- $ref: '#/components/parameters/tenantUri'
- $ref: '#/components/parameters/tenantDbname'
- $ref: '#/components/parameters/tenantSalt'
- $ref: '#/components/parameters/transactionFlag'
- $ref: '#/components/parameters/errorFlag'
- $ref: '#/components/parameters/enterpriseId'
requestBody:
$ref: '#/components/requestBodies/createCustomer'
responses:
'200':
$ref: '#/components/responses/postsuccess'
'400':
$ref: '#/components/responses/postfailed'
components:
parameters:
clientId:
name: Client Id
in: header
description: Client Id
schema:
type: string
example: "ABCD"
tenantId:
name: tenantId
in: header
description: "ABCD"
schema:
type: string
example: "ABCD"
Instead of name: Client Id , Please try with name: ClientId or name: Client_Id. I mean, It should be a single word.
With OpenAPI Is there a way to include examples by reference with the $ref: tag that doesn't not require adding the "value" key?
See examples I've added to the petstore.yaml:
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: http://petstore.swagger.io/v1
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
format: int32
responses:
'200':
description: A paged array of pets
headers:
x-next:
description: A link to the next page of responses
schema:
type: string
content:
application/json:
schema:
$ref: "#/components/schemas/Pets"
example:
$ref: "#/components/examples/animals"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
post:
summary: Create a pet
operationId: createPets
tags:
- pets
responses:
'201':
description: Null response
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/pets/{petId}:
get:
summary: Info for a specific pet
operationId: showPetById
tags:
- pets
parameters:
- name: petId
in: path
required: true
description: The id of the pet to retrieve
schema:
type: string
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
example:
$ref: "#/components/examples/garfield"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
schemas:
Pet:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
Pets:
type: array
items:
$ref: "#/components/schemas/Pet"
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
examples:
garfield:
id: 1
name: garfield
tag: cat
grumpycat:
id: 2
name: grumpycat
tag: cat
odie:
id: 3
name: odie
tag: dog
animals:
- $ref: "#/components/examples/garfield"
- $ref: "#/components/examples/grumpycat"
- $ref: "#/components/examples/odie"
openapi-generator-cli validate says it's invalid OpenAPI as does my OpenAPI plugin for VSCode. Error log output:
Validating spec (/local/petstore.yaml)
Errors:
-attribute components.examples.odie.name is unexpected
-attribute components.examples.garfield.id is unexpected
-attribute components.examples.grumpycat.name is unexpected
-attribute components.examples.animals is not of type `object`
-attribute components.examples.garfield.tag is unexpected
-attribute components.examples.garfield.name is unexpected
-attribute components.examples.odie.tag is unexpected
-attribute components.examples.grumpycat.id is unexpected
-attribute components.examples.grumpycat.tag is unexpected
-attribute components.examples.odie.id is unexpected
[error] Spec has 10 errors.
I can correct the errors by adding a value key like this:
examples:
garfield:
value:
id: 1
name: garfield
tag: cat
grumpycat:
value:
id: 2
name: grumpycat
tag: cat
odie:
value:
id: 3
name: odie
tag: dog
animals:
value:
- $ref: "#/components/examples/garfield"
- $ref: "#/components/examples/grumpycat"
- $ref: "#/components/examples/odie"
The problem with this is that, my examples now include the value property, which I don't want as it's not part of the schema:
{
"value": {
"id": 1,
"name": "garfield",
"tag": "cat"
}
}
Question: Is there a way for me to define the examples by $ref as I have done WITHOUT using introducing the "value" property?
The correct syntax is as follows:
components:
examples:
garfield:
value:
id: 1
name: garfield
tag: cat
grumpycat:
value:
id: 2
name: grumpycat
tag: cat
odie:
value:
id: 3
name: odie
tag: dog
animals:
summary: An array of two animals
value:
- id: 1
name: garfield
tag: cat
- id: 2
name: grumpycat
tag: cat
paths:
/pets:
get:
...
responses:
'200':
description: A paged array of pets
...
content:
application/json:
schema:
$ref: "#/components/schemas/Pets"
examples:
animals:
$ref: "#/components/examples/animals"
/pets/{petId}:
get:
...
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
examples:
garfield:
$ref: "#/components/examples/garfield"
grumpycat:
$ref: '#/components/examples/grumpycat'
odie:
$ref: '#/components/examples/odie'
Explanation:
Examples in the components/examples section must use the Example Object syntax. That is, the actual example value must be wrapped into the value key.
To reference examples from the components/examples section, you must use the examples keyword (plural; not singular example). examples is supported in parameters and in media types, but not in schemas.
Within the literal example value, $ref is not supported. That is, you cannot $ref a part of an example.
I want to write openapi specs for API which will return response as set of object or another object. I am not sure how I can achieve that I have tried many things but when I run codegen for the specs I am getting class OneOfConnectionDTOConnectionPaginatedResponseDTO with error.
I am using below code and I want Set or ConnectionPaginatedResponseDTO in the 200 response
openapi: 3.0.0
servers:
- url: /
info:
title: OIM Manage Connection
version: '1.0'
paths:
'/ManageConnection/viewUserConnection/{oimid}':
get:
tags:
- View Connection
parameters:
- description: OIMID of user
in: path
name: oimid
required: true
schema:
type: string
example: 1234
- description: content type
in: header
name: Content-Type
required: true
schema:
type: string
example: application/json
- description: Start Index of records to be fetched
in: query
name: startIndex
required: false
schema:
type: string
example: 1
- description: Start Index of records to be fetched
in: query
name: count
required: false
schema:
type: string
example: 5
responses:
'200':
description: Connection list returned
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ConnectionDTO'
- $ref: '#/components/schemas/ConnectionPaginatedResponseDTO'
'401':
$ref: '#/components/responses/UnAuthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/DataBaseError'
'501':
$ref: '#/components/responses/MethodError'
components:
responses:
UnAuthorized:
description: Not authorized to access the specified resource
content:
application/json:
schema:
$ref: '#/components/schemas/OIMException'
MandatoryAttributeNotPassedException:
description: Requested resource can't be accessed
content:
application/json:
schema:
$ref: '#/components/schemas/OIMException'
Forbidden:
description: Requested resource can't be accessed
content:
application/json:
schema:
$ref: '#/components/schemas/OIMException'
DataBaseError:
description: Unable to connect to database
content:
application/json:
schema:
$ref: '#/components/schemas/OIMException'
MethodError:
description: Method not implemented
content:
application/json:
schema:
$ref: '#/components/schemas/OIMException'
schemas:
ConnectionDTO:
required:
- access_type
- access_identifier
properties:
add_access_date:
type: string
format: date
access_identifier:
type: string
access_type:
type: string
PIN:
type: string
is_primary_access:
type: string
valid_state:
type: string
friendly_name:
type: string
oimid:
type: string
auth_count:
type: string
type: object
ConnectionPaginatedResponseDTO:
properties:
totalResults:
type: integer
itemsPerPage:
type: integer
startIndex:
type: integer
connections:
$ref: '#/components/schemas/ConnectionDTO'
type: object
OIMException:
properties:
errorMessage:
type: array
items:
type: string
message:
type: string
httpStatus:
type: string
code:
type: integer
type: object
In YAML file I have this:
parameters:
- name: body
in: body
required: true
description: Body of the request.
schema:
$ref: '#/definitions/MinimalProgresstrailEntry'
and it's rendered to this:
:
it doesn't render the reference for the body. It works fine for the responses but not for parameters.
reference definitions:
MinimalProgresstrailEntry:
type: object
properties:
memoText:
type: string
type:
type: string
enum:
- memo
- attachment
- link
Following swagger file works on swagger-editor :
swagger: '2.0'
info:
version: "0.0.0"
title: title
paths:
/persons:
get:
description: test
parameters:
- name: body
in: body
required: true
description: Body of the request.
schema:
$ref: '#/definitions/MinimalProgresstrailEntry'
responses:
200:
description: Successful response
schema:
$ref: '#/definitions/MinimalProgresstrailEntry'
definitions:
MinimalProgresstrailEntry:
type: object
properties:
memoText:
type: string
type:
type: string
enum:
- memo
- attachment
- link
Working on writing an API spec for my service with swagger. I'm using a model definition ('#/definitions/prototype') as the body parameter of both the POST /prototypes and PATCH /prototypes/:id routes.
How do you specify that the PATCH route only accepts a subset of the properties in the body of the request that the POST route does? For example, I want the PATCH /instances/:id route to only allow modification of the mobileDeviceId prototypes property.
swagger: "2.0"
info:
title: ""
description: ""
version: "1.0.0"
host: foo.example.com
schemes:
- https
basePath: /v1
produces:
- application/json
consumes:
- application/json
paths:
/prototypes:
post:
summary: Create new prototype
parameters:
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/Prototype"
responses:
201:
description: Success
schema:
$ref: "#/definitions/SuccessCreated"
403:
description: Prototype limit exceeded error
schema:
$ref: "#/definitions/Error"
default:
description: Unexpected error
schema:
$ref: "#/definitions/Error"
/prototypes/{id}:
patch:
summary: Update an existing prototype's properties
parameters:
- name: id
in: path
type: number
description: ID property of a prototype
required: true
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/Prototype"
responses:
200:
description: Success
definitions:
Prototype:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
mobileDeviceId:
type: number
SuccessCreated:
type: object
description: Returned as response to successful resource create request
properties:
code:
type: number
default: 201
message:
type: string
Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
fields:
type: string
Swagger uses json-schema: http://json-schema.org
$refs provide you w/ a way to repeat existing json-schema at a new path.
Notice that you are using a $ref for patch/parameters/-name:prototype/schema.
You can create a new definition just for patch in the definitions section and reference it instead
swagger: "2.0"
info:
title: ""
description: ""
version: "1.0.0"
host: foo.example.com
schemes:
- https
basePath: /v1
produces:
- application/json
consumes:
- application/json
paths:
/prototypes:
post:
summary: Create new prototype
parameters:
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/Prototype"
responses:
201:
description: Success
schema:
$ref: "#/definitions/SuccessCreated"
403:
description: Prototype limit exceeded error
schema:
$ref: "#/definitions/Error"
default:
description: Unexpected error
schema:
$ref: "#/definitions/Error"
/prototypes/{id}:
patch:
summary: Update an existing prototype's properties
parameters:
- name: id
in: path
type: number
description: ID property of a prototype
required: true
- name: prototype
in: body
description: Prototype object
required: true
schema:
$ref: "#/definitions/PatchPrototype"
responses:
200:
description: Success
definitions:
Prototype:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
mobileDeviceId:
type: number
PatchPrototype:
type: object
properties:
mobileDeviceId:
type: number
SuccessCreated:
type: object
description: Returned as response to successful resource create request
properties:
code:
type: number
default: 201
message:
type: string
Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
fields:
type: string