Skip to content

Instantly share code, notes, and snippets.

@ponelat

ponelat/README.md

Last active November 23, 2021 13:52
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save ponelat/9de63f103c502f48066085941118037e to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save ponelat/9de63f103c502f48066085941118037e to your computer and use it in GitHub Desktop.
Download ZIP
Overlay for generated OpenAPI definition
Raw
README.md

Generated OpenAPI definition with Overlay

This is to demonstrate the use-case of Overlays for documentation writers.

The original.json file was generated from a swagger-core sample (aka Code-first) and original.yml is the same definition but in YAML.

This is an effort of using real tools and as close to real issues as possible. Instead of simpler conrvied examples, although going forward simpler examples will be better (for readability at least)!

When we stick this into https://editor.swagger.io we find the following errors... image

We also have a little warning where an invalid type is used in an enum... image

enum value should conform to its schema's type.

How an Overlay could "fix" the main issues

Adding the Overlay overlay.yml ( should update the definition and produce the following new-openapi.yml. Which addresses the core issues of the generated definition.

Notes

  • Used https://jsonpath.com/ and https://jmespath.org/ to help test the target paths.
  • Added tags which felt useful to classifying mutations. Possibly useful to group (and if we need to merge two Overlays into one, tags could be useful in distinguishing).
  • This example used all pointers to address issues, no "real queries" were needed.
  • Lots of opportunites for different tooling to help author Overlays. In this case, it could've been aided by simply "editing the original definition" which instead of mutating the original, should produce an Overlay defintion. Much like a patch file.
Raw
new-openapi.yml
openapi: 3.0.1
info:
title: Swagger Pet Sample App Config File
description: 'This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.'
termsOfService: http://swagger.io/terms/
contact:
email: apiteam@swagger.io
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: '1.0'
paths:
/sample/pet/findByTags:
get:
tags:
- pets
summary: Finds Pets by tags
description: Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.
operationId: findPetsByTags
parameters:
- name: tags
in: query
description: Tags to filter by
required: true
schema:
type: string
responses:
'400':
description: Invalid tag value
default:
description: Pets matching criteria
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
/sample/pet/{petId}:
get:
tags:
- pets
summary: Find pet by ID
description: Returns a pet when 0 < ID <= 10. ID > 10 or nonintegers will simulate API error conditions
operationId: getPetById
parameters:
- name: petId
in: path
description: ID of pet that needs to be fetched
required: true
schema:
type: integer
description: param ID of pet that needs to be fetched
format: int64
enum:
- 1
- 2
- 3
responses:
'400':
description: Invalid ID supplied
'404':
description: Pet not found
default:
description: The pet
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
/sample/pet:
put:
tags:
- pets
summary: Update an existing pet
operationId: updatePet
requestBody:
description: Pet object that needs to be added to the store
content:
'*/*':
schema:
$ref: '#/components/schemas/Pet'
required: true
responses:
'400':
description: Invalid ID supplied
'404':
description: Pet not found
'405':
description: Validation exception
post:
tags:
- pets
summary: Add a new pet to the store
operationId: addPet
requestBody:
description: Pet object that needs to be added to the store
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
required: true
responses:
'405':
description: Invalid input
/sample/pet/findByStatus:
get:
tags:
- pets
summary: Finds Pets by status
description: Multiple status values can be provided with comma seperated strings
operationId: findPetsByStatus
parameters:
- name: status
in: query
description: Status values that need to be considered for filter
required: true
schema:
type: string
enum:
- available
- pending
- sold
default: available
- name: skip
in: query
schema:
type: integer
format: int32
- name: limit
in: query
schema:
type: integer
format: int32
responses:
'400':
description: Invalid status value
default:
description: |
Returns a list of pets.
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
/sample/store/order/{orderId}:
get:
summary: Find purchase order by ID
description: For valid response try integer IDs with value >= 1 and <= 10. Other values will generated exceptions
operationId: getOrderById
parameters:
- name: X-TOKEN
in: header
schema:
type: string
description: The an expiring token assigned to a user
- name: X-REQUEST-HASH
in: header
schema:
type: string
description: A HMAC-SHA hash based on the request being made
- name: orderId
in: path
description: ID of order to fetch
required: true
schema:
type: integer
format: int64
responses:
'400':
description: Invalid ID supplied
'404':
description: Order not found
default:
description: |
Returns a Store.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
application/xml:
schema:
$ref: '#/components/schemas/Order'
delete:
summary: Delete purchase order by ID
operationId: deleteOrder
parameters:
- name: X-TOKEN
in: header
schema:
type: string
description: The an expiring token assigned to a user
- name: X-REQUEST-HASH
in: header
schema:
type: string
description: A HMAC-SHA hash based on the request being made
- name: orderId
in: path
description: ID of order to delete
required: true
schema:
type: integer
format: int64
responses:
'400':
description: Invalid ID supplied
'404':
description: Order not found
/sample/store/order:
post:
summary: Place an order for a pet
operationId: placeOrder
parameters:
- name: X-TOKEN
in: header
schema:
type: string
description: The an expiring token assigned to a user
- name: X-REQUEST-HASH
in: header
schema:
type: string
description: A HMAC-SHA hash based on the request being made
requestBody:
description: order placed for purchasing the pet
content:
'*/*':
schema:
$ref: '#/components/schemas/Order'
required: true
responses:
'400':
description: Invalid Order
default:
description: |
Returns a store.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
application/xml:
schema:
$ref: '#/components/schemas/Order'
/sample/test/more/otherStatus:
get:
description: Get the other status!
operationId: otherStatus
parameters:
- name: qp
in: query
schema:
type: integer
format: int32
responses:
default:
description: default response
content:
application/json:
schema:
type: string
/sample/test/status:
get:
description: Get status
operationId: getStatus
responses:
default:
description: default response
content:
application/json:
schema:
type: string
/sample/user/createWithArray:
post:
tags:
- users
summary: Creates list of users with given input array
operationId: createUsersWithArrayInput
requestBody:
description: List of user object
content:
'*/*':
schema:
type: array
items:
$ref: '#/components/schemas/User'
required: true
responses:
default:
description: default response
content:
application/json: {}
application/xml: {}
/sample/user/createWithList:
post:
tags:
- users
summary: Creates list of users with given input array
operationId: createUsersWithListInput
requestBody:
description: List of user object
content:
'*/*':
schema:
type: array
items:
$ref: '#/components/schemas/User'
required: true
responses:
default:
description: default response
content:
application/json: {}
application/xml: {}
/sample/user/{username}:
get:
tags:
- users
summary: Get user by user name
operationId: getUserByName
parameters:
- name: username
in: path
description: 'The name that needs to be fetched. Use user1 for testing. '
required: true
schema:
type: string
responses:
'400':
description: User not found
default:
description: The user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
put:
tags:
- users
summary: Updated user
description: This can only be done by the logged in user.
operationId: updateUser
parameters:
- name: username
in: path
description: name that need to be deleted
required: true
schema:
type: string
requestBody:
description: Updated user object
content:
'*/*':
schema:
$ref: '#/components/schemas/User'
required: true
responses:
'200':
description: user updated
'400':
description: Invalid user supplied
'404':
description: User not found
delete:
tags:
- users
summary: Delete user
description: This can only be done by the logged in user.
operationId: deleteUser
parameters:
- name: username
in: path
description: The name that needs to be deleted
required: true
schema:
type: string
responses:
'200':
description: user deteled
'400':
description: Invalid username supplied
'404':
description: User not found
/sample/user/login:
get:
tags:
- users
summary: Logs user into the system
operationId: loginUser
parameters:
- name: username
in: query
description: The user name for login
required: true
schema:
type: string
- name: password
in: query
description: The password for login in clear text
required: true
schema:
type: string
responses:
'400':
description: Invalid username/password supplied
default:
description: Successfully logged in
content:
application/json:
schema:
type: string
application/xml:
schema:
type: string
/sample/user/logout:
get:
tags:
- users
summary: Logs out current logged in user session
operationId: logoutUser
responses:
default:
description: default response
content:
application/json: {}
application/xml: {}
/sample/user:
post:
tags:
- users
summary: Create user
description: This can only be done by the logged in user.
operationId: createUser
requestBody:
description: Created user object
content:
'*/*':
schema:
$ref: '#/components/schemas/User'
required: true
responses:
default:
description: default response
content:
application/json: {}
application/xml: {}
components:
schemas:
Category:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
xml:
name: Category
Pet:
required:
- lorem
type: object
properties:
id:
type: integer
format: int64
category:
$ref: '#/components/schemas/Category'
name:
type: string
photoUrls:
type: array
xml:
wrapped: true
items:
type: string
xml:
name: photoUrl
tags:
type: array
xml:
wrapped: true
items:
$ref: '#/components/schemas/Tag'
status:
type: string
description: pet status in the store
enum:
- available,pending,sold
lorem:
type: array
example:
- 2
- 3
items:
type: integer
format: int32
xml:
name: Pet
Tag:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
xml:
name: Tag
Order:
type: object
properties:
id:
type: integer
format: int64
petId:
type: integer
format: int64
quantity:
type: integer
format: int32
shipDate:
type: string
format: date-time
status:
type: string
description: Order Status
enum:
- placed, approved, delivered
complete:
type: boolean
xml:
name: Order
User:
type: object
properties:
id:
type: integer
format: int64
username:
type: string
firstName:
type: string
lastName:
type: string
email:
type: string
password:
type: string
phone:
type: string
userStatus:
type: integer
description: User Status
format: int32
nullable: true
enum:
- null
xml:
name: User
Raw
original.json
{
"openapi" : "3.0.1",
"info" : {
"title" : "Swagger Pet Sample App Config File",
"description" : "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.",
"termsOfService" : "http://swagger.io/terms/",
"contact" : {
"email" : "apiteam@swagger.io"
},
"license" : {
"name" : "Apache 2.0",
"url" : "http://www.apache.org/licenses/LICENSE-2.0.html"
},
"version" : "1.0"
},
"paths" : {
"/sample/pet/findByTags" : {
"get" : {
"tags" : [ "pets" ],
"summary" : "Finds Pets by tags",
"description" : "Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.",
"operationId" : "findPetsByTags",
"parameters" : [ {
"name" : "tags",
"in" : "query",
"description" : "Tags to filter by",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"default" : {
"description" : "Pets matching criteria",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Pet"
}
}
}
},
"400" : {
"description" : "Invalid tag value"
}
}
}
},
"/sample/pet/{petId}" : {
"get" : {
"tags" : [ "pets" ],
"summary" : "Find pet by ID",
"description" : "Returns a pet when 0 < ID <= 10. ID > 10 or nonintegers will simulate API error conditions",
"operationId" : "getPetById",
"parameters" : [ {
"name" : "petId",
"in" : "path",
"description" : "ID of pet that needs to be fetched",
"required" : true,
"schema" : {
"type" : "integer",
"description" : "param ID of pet that needs to be fetched",
"format" : "int64",
"enum" : [ 1, 2, 3 ]
}
} ],
"responses" : {
"default" : {
"description" : "The pet",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Pet"
}
},
"application/xml" : {
"schema" : {
"$ref" : "#/components/schemas/Pet"
}
}
}
},
"400" : {
"description" : "Invalid ID supplied"
},
"404" : {
"description" : "Pet not found"
}
}
}
},
"/sample/pet" : {
"put" : {
"tags" : [ "pets" ],
"summary" : "Update an existing pet",
"operationId" : "updatePet",
"requestBody" : {
"description" : "Pet object that needs to be added to the store",
"content" : {
"*/*" : {
"schema" : {
"$ref" : "#/components/schemas/Pet"
}
}
},
"required" : true
},
"responses" : {
"400" : {
"description" : "Invalid ID supplied"
},
"404" : {
"description" : "Pet not found"
},
"405" : {
"description" : "Validation exception"
}
}
},
"post" : {
"tags" : [ "pets" ],
"summary" : "Add a new pet to the store",
"operationId" : "addPet",
"requestBody" : {
"description" : "Pet object that needs to be added to the store",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Pet"
}
}
},
"required" : true
},
"responses" : {
"405" : {
"description" : "Invalid input"
}
}
}
},
"/sample/pet/findByStatus" : {
"get" : {
"tags" : [ "pets" ],
"summary" : "Finds Pets by status",
"description" : "Multiple status values can be provided with comma seperated strings",
"operationId" : "findPetsByStatus",
"parameters" : [ {
"name" : "status",
"in" : "query",
"description" : "Status values that need to be considered for filter",
"required" : true,
"schema" : {
"type" : "string",
"enum" : [ "available", "pending", "sold" ],
"default" : "available"
}
}, {
"name" : "skip",
"in" : "query",
"schema" : {
"type" : "integer",
"format" : "int32"
}
}, {
"name" : "limit",
"in" : "query",
"schema" : {
"type" : "integer",
"format" : "int32"
}
} ],
"responses" : {
"default" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Pet"
}
}
}
},
"400" : {
"description" : "Invalid status value"
}
}
}
},
"/sample/store/order/{orderId}" : {
"get" : {
"summary" : "Find purchase order by ID",
"description" : "For valid response try integer IDs with value >= 1 and <= 10. Other values will generated exceptions",
"operationId" : "getOrderById",
"parameters" : [ {
"name" : "X-TOKEN",
"in" : "header",
"schema" : {
"type" : "string",
"description" : "The an expiring token assigned to a user"
}
}, {
"name" : "X-REQUEST-HASH",
"in" : "header",
"schema" : {
"type" : "string",
"description" : "A HMAC-SHA hash based on the request being made"
}
}, {
"name" : "orderId",
"in" : "path",
"description" : "ID of order to fetch",
"required" : true,
"schema" : {
"type" : "integer",
"format" : "int64"
}
} ],
"responses" : {
"default" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Order"
}
},
"application/xml" : {
"schema" : {
"$ref" : "#/components/schemas/Order"
}
}
}
},
"400" : {
"description" : "Invalid ID supplied"
},
"404" : {
"description" : "Order not found"
}
}
},
"delete" : {
"summary" : "Delete purchase order by ID",
"operationId" : "deleteOrder",
"parameters" : [ {
"name" : "X-TOKEN",
"in" : "header",
"schema" : {
"type" : "string",
"description" : "The an expiring token assigned to a user"
}
}, {
"name" : "X-REQUEST-HASH",
"in" : "header",
"schema" : {
"type" : "string",
"description" : "A HMAC-SHA hash based on the request being made"
}
}, {
"name" : "orderId",
"in" : "path",
"description" : "ID of order to delete",
"required" : true,
"schema" : {
"type" : "integer",
"format" : "int64"
}
} ],
"responses" : {
"400" : {
"description" : "Invalid ID supplied"
},
"404" : {
"description" : "Order not found"
}
}
}
},
"/sample/store/order" : {
"post" : {
"summary" : "Place an order for a pet",
"operationId" : "placeOrder",
"parameters" : [ {
"name" : "X-TOKEN",
"in" : "header",
"schema" : {
"type" : "string",
"description" : "The an expiring token assigned to a user"
}
}, {
"name" : "X-REQUEST-HASH",
"in" : "header",
"schema" : {
"type" : "string",
"description" : "A HMAC-SHA hash based on the request being made"
}
} ],
"requestBody" : {
"description" : "order placed for purchasing the pet",
"content" : {
"*/*" : {
"schema" : {
"$ref" : "#/components/schemas/Order"
}
}
},
"required" : true
},
"responses" : {
"default" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Order"
}
},
"application/xml" : {
"schema" : {
"$ref" : "#/components/schemas/Order"
}
}
}
},
"400" : {
"description" : "Invalid Order"
}
}
}
},
"/sample/test/more/otherStatus" : {
"get" : {
"description" : "Get the other status!",
"operationId" : "otherStatus",
"parameters" : [ {
"name" : "qp",
"in" : "query",
"schema" : {
"type" : "integer",
"format" : "int32"
}
} ],
"responses" : {
"default" : {
"description" : "default response",
"content" : {
"application/json" : {
"schema" : {
"type" : "string"
}
}
}
}
}
}
},
"/sample/test/status" : {
"get" : {
"description" : "Get status",
"operationId" : "getStatus",
"responses" : {
"default" : {
"description" : "default response",
"content" : {
"application/json" : {
"schema" : {
"type" : "string"
}
}
}
}
}
}
},
"/sample/user/createWithArray" : {
"post" : {
"tags" : [ "users" ],
"summary" : "Creates list of users with given input array",
"operationId" : "createUsersWithArrayInput",
"requestBody" : {
"description" : "List of user object",
"content" : {
"*/*" : {
"schema" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/User"
}
}
}
},
"required" : true
},
"responses" : {
"default" : {
"description" : "default response",
"content" : {
"application/json" : { },
"application/xml" : { }
}
}
}
}
},
"/sample/user/createWithList" : {
"post" : {
"tags" : [ "users" ],
"summary" : "Creates list of users with given input array",
"operationId" : "createUsersWithListInput",
"requestBody" : {
"description" : "List of user object",
"content" : {
"*/*" : {
"schema" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/User"
}
}
}
},
"required" : true
},
"responses" : {
"default" : {
"description" : "default response",
"content" : {
"application/json" : { },
"application/xml" : { }
}
}
}
}
},
"/sample/user/{username}" : {
"get" : {
"tags" : [ "users" ],
"summary" : "Get user by user name",
"operationId" : "getUserByName",
"parameters" : [ {
"name" : "username",
"in" : "path",
"description" : "The name that needs to be fetched. Use user1 for testing. ",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"default" : {
"description" : "The user",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/User"
}
}
}
},
"400" : {
"description" : "User not found"
}
}
},
"put" : {
"tags" : [ "users" ],
"summary" : "Updated user",
"description" : "This can only be done by the logged in user.",
"operationId" : "updateUser",
"parameters" : [ {
"name" : "username",
"in" : "path",
"description" : "name that need to be deleted",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"requestBody" : {
"description" : "Updated user object",
"content" : {
"*/*" : {
"schema" : {
"$ref" : "#/components/schemas/User"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "user updated"
},
"400" : {
"description" : "Invalid user supplied"
},
"404" : {
"description" : "User not found"
}
}
},
"delete" : {
"tags" : [ "users" ],
"summary" : "Delete user",
"description" : "This can only be done by the logged in user.",
"operationId" : "deleteUser",
"parameters" : [ {
"name" : "username",
"in" : "path",
"description" : "The name that needs to be deleted",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "user deteled"
},
"400" : {
"description" : "Invalid username supplied"
},
"404" : {
"description" : "User not found"
}
}
}
},
"/sample/user/login" : {
"get" : {
"tags" : [ "users" ],
"summary" : "Logs user into the system",
"operationId" : "loginUser",
"parameters" : [ {
"name" : "username",
"in" : "query",
"description" : "The user name for login",
"required" : true,
"schema" : {
"type" : "string"
}
}, {
"name" : "password",
"in" : "query",
"description" : "The password for login in clear text",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"default" : {
"description" : "Successfully logged in",
"content" : {
"application/json" : {
"schema" : {
"type" : "string"
}
},
"application/xml" : {
"schema" : {
"type" : "string"
}
}
}
},
"400" : {
"description" : "Invalid username/password supplied"
}
}
}
},
"/sample/user/logout" : {
"get" : {
"tags" : [ "users" ],
"summary" : "Logs out current logged in user session",
"operationId" : "logoutUser",
"responses" : {
"default" : {
"description" : "default response",
"content" : {
"application/json" : { },
"application/xml" : { }
}
}
}
}
},
"/sample/user" : {
"post" : {
"tags" : [ "users" ],
"summary" : "Create user",
"description" : "This can only be done by the logged in user.",
"operationId" : "createUser",
"requestBody" : {
"description" : "Created user object",
"content" : {
"*/*" : {
"schema" : {
"$ref" : "#/components/schemas/User"
}
}
},
"required" : true
},
"responses" : {
"default" : {
"description" : "default response",
"content" : {
"application/json" : { },
"application/xml" : { }
}
}
}
}
}
},
"components" : {
"schemas" : {
"Category" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer",
"format" : "int64"
},
"name" : {
"type" : "string"
}
},
"xml" : {
"name" : "Category"
}
},
"Pet" : {
"required" : [ "lorem" ],
"type" : "object",
"properties" : {
"id" : {
"type" : "integer",
"format" : "int64"
},
"category" : {
"$ref" : "#/components/schemas/Category"
},
"name" : {
"type" : "string"
},
"photoUrls" : {
"type" : "array",
"xml" : {
"wrapped" : true
},
"items" : {
"type" : "string",
"xml" : {
"name" : "photoUrl"
}
}
},
"tags" : {
"type" : "array",
"xml" : {
"wrapped" : true
},
"items" : {
"$ref" : "#/components/schemas/Tag"
}
},
"status" : {
"type" : "string",
"description" : "pet status in the store",
"enum" : [ "available,pending,sold" ]
},
"lorem" : {
"type" : "array",
"example" : [ 2, 3 ],
"items" : {
"type" : "integer",
"format" : "int32"
}
}
},
"xml" : {
"name" : "Pet"
}
},
"Tag" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer",
"format" : "int64"
},
"name" : {
"type" : "string"
}
},
"xml" : {
"name" : "Tag"
}
},
"Order" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer",
"format" : "int64"
},
"petId" : {
"type" : "integer",
"format" : "int64"
},
"quantity" : {
"type" : "integer",
"format" : "int32"
},
"shipDate" : {
"type" : "string",
"format" : "date-time"
},
"status" : {
"type" : "string",
"description" : "Order Status",
"enum" : [ "placed, approved, delivered" ]
},
"complete" : {
"type" : "boolean"
}
},
"xml" : {
"name" : "Order"
}
},
"User" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer",
"format" : "int64"
},
"username" : {
"type" : "string"
},
"firstName" : {
"type" : "string"
},
"lastName" : {
"type" : "string"
},
"email" : {
"type" : "string"
},
"password" : {
"type" : "string"
},
"phone" : {
"type" : "string"
},
"userStatus" : {
"type" : "integer",
"description" : "User Status",
"format" : "int32",
"enum" : [ null ]
}
},
"xml" : {
"name" : "User"
}
}
}
}
}
Raw
original.yml
openapi: 3.0.1
info:
title: Swagger Pet Sample App Config File
description: 'This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.'
termsOfService: http://swagger.io/terms/
contact:
email: apiteam@swagger.io
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: '1.0'
paths:
/sample/pet/findByTags:
get:
tags:
- pets
summary: Finds Pets by tags
description: Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.
operationId: findPetsByTags
parameters:
- name: tags
in: query
description: Tags to filter by
required: true
schema:
type: string
responses:
'400':
description: Invalid tag value
default:
description: Pets matching criteria
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
/sample/pet/{petId}:
get:
tags:
- pets
summary: Find pet by ID
description: Returns a pet when 0 < ID <= 10. ID > 10 or nonintegers will simulate API error conditions
operationId: getPetById
parameters:
- name: petId
in: path
description: ID of pet that needs to be fetched
required: true
schema:
type: integer
description: param ID of pet that needs to be fetched
format: int64
enum:
- 1
- 2
- 3
responses:
'400':
description: Invalid ID supplied
'404':
description: Pet not found
default:
description: The pet
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
application/xml:
schema:
$ref: '#/components/schemas/Pet'
/sample/pet:
put:
tags:
- pets
summary: Update an existing pet
operationId: updatePet
requestBody:
description: Pet object that needs to be added to the store
content:
'*/*':
schema:
$ref: '#/components/schemas/Pet'
required: true
responses:
'400':
description: Invalid ID supplied
'404':
description: Pet not found
'405':
description: Validation exception
post:
tags:
- pets
summary: Add a new pet to the store
operationId: addPet
requestBody:
description: Pet object that needs to be added to the store
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
required: true
responses:
'405':
description: Invalid input
/sample/pet/findByStatus:
get:
tags:
- pets
summary: Finds Pets by status
description: Multiple status values can be provided with comma seperated strings
operationId: findPetsByStatus
parameters:
- name: status
in: query
description: Status values that need to be considered for filter
required: true
schema:
type: string
enum:
- available
- pending
- sold
default: available
- name: skip
in: query
schema:
type: integer
format: int32
- name: limit
in: query
schema:
type: integer
format: int32
responses:
'400':
description: Invalid status value
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
/sample/store/order/{orderId}:
get:
summary: Find purchase order by ID
description: For valid response try integer IDs with value >= 1 and <= 10. Other values will generated exceptions
operationId: getOrderById
parameters:
- name: X-TOKEN
in: header
schema:
type: string
description: The an expiring token assigned to a user
- name: X-REQUEST-HASH
in: header
schema:
type: string
description: A HMAC-SHA hash based on the request being made
- name: orderId
in: path
description: ID of order to fetch
required: true
schema:
type: integer
format: int64
responses:
'400':
description: Invalid ID supplied
'404':
description: Order not found
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
application/xml:
schema:
$ref: '#/components/schemas/Order'
delete:
summary: Delete purchase order by ID
operationId: deleteOrder
parameters:
- name: X-TOKEN
in: header
schema:
type: string
description: The an expiring token assigned to a user
- name: X-REQUEST-HASH
in: header
schema:
type: string
description: A HMAC-SHA hash based on the request being made
- name: orderId
in: path
description: ID of order to delete
required: true
schema:
type: integer
format: int64
responses:
'400':
description: Invalid ID supplied
'404':
description: Order not found
/sample/store/order:
post:
summary: Place an order for a pet
operationId: placeOrder
parameters:
- name: X-TOKEN
in: header
schema:
type: string
description: The an expiring token assigned to a user
- name: X-REQUEST-HASH
in: header
schema:
type: string
description: A HMAC-SHA hash based on the request being made
requestBody:
description: order placed for purchasing the pet
content:
'*/*':
schema:
$ref: '#/components/schemas/Order'
required: true
responses:
'400':
description: Invalid Order
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
application/xml:
schema:
$ref: '#/components/schemas/Order'
/sample/test/more/otherStatus:
get:
description: Get the other status!
operationId: otherStatus
parameters:
- name: qp
in: query
schema:
type: integer
format: int32
responses:
default:
description: default response
content:
application/json:
schema:
type: string
/sample/test/status:
get:
description: Get status
operationId: getStatus
responses:
default:
description: default response
content:
application/json:
schema:
type: string
/sample/user/createWithArray:
post:
tags:
- users
summary: Creates list of users with given input array
operationId: createUsersWithArrayInput
requestBody:
description: List of user object
content:
'*/*':
schema:
type: array
items:
$ref: '#/components/schemas/User'
required: true
responses:
default:
description: default response
content:
application/json: {}
application/xml: {}
/sample/user/createWithList:
post:
tags:
- users
summary: Creates list of users with given input array
operationId: createUsersWithListInput
requestBody:
description: List of user object
content:
'*/*':
schema:
type: array
items:
$ref: '#/components/schemas/User'
required: true
responses:
default:
description: default response
content:
application/json: {}
application/xml: {}
/sample/user/{username}:
get:
tags:
- users
summary: Get user by user name
operationId: getUserByName
parameters:
- name: username
in: path
description: 'The name that needs to be fetched. Use user1 for testing. '
required: true
schema:
type: string
responses:
'400':
description: User not found
default:
description: The user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
put:
tags:
- users
summary: Updated user
description: This can only be done by the logged in user.
operationId: updateUser
parameters:
- name: username
in: path
description: name that need to be deleted
required: true
schema:
type: string
requestBody:
description: Updated user object
content:
'*/*':
schema:
$ref: '#/components/schemas/User'
required: true
responses:
'200':
description: user updated
'400':
description: Invalid user supplied
'404':
description: User not found
delete:
tags:
- users
summary: Delete user
description: This can only be done by the logged in user.
operationId: deleteUser
parameters:
- name: username
in: path
description: The name that needs to be deleted
required: true
schema:
type: string
responses:
'200':
description: user deteled
'400':
description: Invalid username supplied
'404':
description: User not found
/sample/user/login:
get:
tags:
- users
summary: Logs user into the system
operationId: loginUser
parameters:
- name: username
in: query
description: The user name for login
required: true
schema:
type: string
- name: password
in: query
description: The password for login in clear text
required: true
schema:
type: string
responses:
'400':
description: Invalid username/password supplied
default:
description: Successfully logged in
content:
application/json:
schema:
type: string
application/xml:
schema:
type: string
/sample/user/logout:
get:
tags:
- users
summary: Logs out current logged in user session
operationId: logoutUser
responses:
default:
description: default response
content:
application/json: {}
application/xml: {}
/sample/user:
post:
tags:
- users
summary: Create user
description: This can only be done by the logged in user.
operationId: createUser
requestBody:
description: Created user object
content:
'*/*':
schema:
$ref: '#/components/schemas/User'
required: true
responses:
default:
description: default response
content:
application/json: {}
application/xml: {}
components:
schemas:
Category:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
xml:
name: Category
Pet:
required:
- lorem
type: object
properties:
id:
type: integer
format: int64
category:
$ref: '#/components/schemas/Category'
name:
type: string
photoUrls:
type: array
xml:
wrapped: true
items:
type: string
xml:
name: photoUrl
tags:
type: array
xml:
wrapped: true
items:
$ref: '#/components/schemas/Tag'
status:
type: string
description: pet status in the store
enum:
- available,pending,sold
lorem:
type: array
example:
- 2
- 3
items:
type: integer
format: int32
xml:
name: Pet
Tag:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
xml:
name: Tag
Order:
type: object
properties:
id:
type: integer
format: int64
petId:
type: integer
format: int64
quantity:
type: integer
format: int32
shipDate:
type: string
format: date-time
status:
type: string
description: Order Status
enum:
- placed, approved, delivered
complete:
type: boolean
xml:
name: Order
User:
type: object
properties:
id:
type: integer
format: int64
username:
type: string
firstName:
type: string
lastName:
type: string
email:
type: string
password:
type: string
phone:
type: string
userStatus:
type: integer
description: User Status
format: int32
enum:
- null
xml:
name: User
Raw
overlay.yml
overlay: 1.0.0
info:
title: Fix original.yml
version: 1.0.0
extends: ./openapi.yml
updates:
- target: "$.paths./sample/pet/findByStatus.get.responses.default" # For JMESPath: "@.paths.\"/sample/pet/findByStatus\".get.responses.default"
tags: # Not part of Overlays (yet)
- documentation # Might be nice to have tags to group up types of mutations.
- pet
update:
description: |
Returns a list of pets.
- target: "$.paths./sample/store/order/{orderId}.get.responses.default" # For JMESPath: "@.paths.\"/sample/store/order/{orderId}\".get.responses.default"
tags:
- documentation
- store
update:
description: |
Returns a Store.
- target: "$.paths./sample/store/order.post.responses.default" # For JMESPath: "@.paths.\"/sample/store/order\".get.responses.default"
tags:
- documentation
- store
update:
description: |
Returns a store.
- target: "$.components.schemas.User.properties.userStatus" # For JMESPath: "@.components.schemas.User.properties.userStatus"
description: Allow `null` for `userStatus`
tags:
- type
- user
update:
nullable: true
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment