In my Swagger documentation, I have to use same pattern multiple time. Currently, it is placed duplicated.
One thing I improved is that making common parameter (by declaring it inside components). But couldn't find anything to avoid this duplicate pattern between parameters and schemas.
Is there any way, I can use declare this pattern once and re-use it wherever it's needed?
My Swagger looks something like:
openapi: 3.0.3
info:
title: My System
description: Self contained system
version: 1.0.0
servers:
- url: /a/{aId}/
description: Contains the partition
security:
- bearerAuth: []
paths:
"/x/{xId}/y/{yId}/z/{zId}":
get:
x-horizon-permission: "geo.floorplan.read"
tags:
- myTag
operationId: getValue
description: Get Value
parameters:
- name: xId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: yId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: zId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
responses:
"200":
description: OK
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Response'
patch:
tags:
- myTag
operationId: Update
description: Update Data
parameters:
- name: xId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: yId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
- name: zId
in: path
required: true
schema:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
requestBody:
required: true
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Request'
responses:
"200":
description: OK
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Response'
components:
schemas:
Request:
type: object
properties:
data:
type: object
properties:
type:
type: string
id:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
Response:
type: object
properties:
links:
type: object
properties:
self:
type: string
data:
$ref: '#/components/schemas/Data'
Data:
type: object
properties:
type:
type: string
id:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
GeometryError:
type: object
required:
- code
- status
- title
properties:
id:
type: string
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
status:
type: string
example: 400
title:
type: string
detail:
type: string
meta:
type: object
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
Define a schema with this pattern:
components:
schema:
UUID:
type: string
format: uuid # for tools/codegens that have built-in support for UUIDs
pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
Then you can reference this schema from other schemas and parameter definitions:
parameters:
- name: xId
in: path
required: true
schema:
$ref: '#/components/schemas/UUID' # <-----
- name: yId
in: path
required: true
schema:
$ref: '#/components/schemas/UUID' # <-----
...
schemas:
Request:
type: object
properties:
data:
type: object
properties:
type:
type: string
id:
$ref: '#/components/schemas/UUID' # <-----
Related
Use path parameter petId as field value for id in request body. How can we do it?
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: http://petstore.swagger.io/v1
paths:
/pets/{petId}:
put:
summary: Info for a specific pet
operationId: UpdatePetInfoById
tags:
- pets
parameters:
- name: petId
in: path
required: true
description: The id of the pet to retrieve
schema:
type: string
requestBody:
description: Info about a new pet
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
responses:
'200':
description: Expected response to a valid request
components:
schemas:
Pet:
required:
- id
- name
properties:
id: _{$request.path.petId}_
name:
type: string
tag:
type: string
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
In the following Swagger definition, I need the parameter labelValue to be of type LabelValueObject, so that it will be validated and correctly deserialized. However, I can't figure out the syntax! How can that be done?
swagger: "2.0"
paths:
/competition:
post:
parameters:
- name: labelValue
in: formData
type: array
items:
type: string ### this has to be a LabelValueObject ###
responses:
default:
description: Error
schema:
$ref: "#/definitions/AnyResponse"
definitions:
AnyResponse:
properties:
any:
type: string
LabelValueObject:
properties:
label:
type: string
value:
type: string
required:
- label
- value
The only way to pass an object as a parameter is to put it in the body (in: body) and then define this object in schema (inline definition or reference to an predefined object with $ref). Here's a full example:
swagger: "2.0"
info:
title: A dummy title
version: 1.0.0
paths:
/competition:
post:
parameters:
- name: labelValue
in: body
schema:
$ref: '#/definitions/LabelValueObject'
responses:
default:
description: Error
schema:
$ref: "#/definitions/AnyResponse"
definitions:
AnyResponse:
properties:
any:
type: string
LabelValueObject:
properties:
label:
type: string
value:
type: string
required:
- label
- value
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