Add example OpenAPI specification
This commit is contained in:
297
examples/petstore.yaml
Normal file
297
examples/petstore.yaml
Normal file
@@ -0,0 +1,297 @@
|
|||||||
|
openapi: 3.0.0
|
||||||
|
info:
|
||||||
|
title: Pet Store API
|
||||||
|
description: A sample API for managing pets in a store
|
||||||
|
version: 1.0.0
|
||||||
|
servers:
|
||||||
|
- url: https://api.petstore.example.com/v1
|
||||||
|
description: Production server
|
||||||
|
- url: http://localhost:4010
|
||||||
|
description: Mock server for testing
|
||||||
|
tags:
|
||||||
|
- name: pets
|
||||||
|
description: Operations on pets
|
||||||
|
- name: store
|
||||||
|
description: Store management operations
|
||||||
|
- name: users
|
||||||
|
description: User management operations
|
||||||
|
|
||||||
|
paths:
|
||||||
|
/pets:
|
||||||
|
get:
|
||||||
|
summary: List all pets
|
||||||
|
description: Returns a list of pets with optional filtering
|
||||||
|
operationId: listPets
|
||||||
|
tags:
|
||||||
|
- pets
|
||||||
|
parameters:
|
||||||
|
- name: status
|
||||||
|
in: query
|
||||||
|
description: Filter pets by status
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
enum:
|
||||||
|
- available
|
||||||
|
- pending
|
||||||
|
- sold
|
||||||
|
- name: limit
|
||||||
|
in: query
|
||||||
|
description: Maximum number of pets to return
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
default: 20
|
||||||
|
- name: offset
|
||||||
|
in: query
|
||||||
|
description: Number of pets to skip
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
default: 0
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: A list of pets
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/Pet'
|
||||||
|
post:
|
||||||
|
summary: Create a new pet
|
||||||
|
description: Creates a new pet in the store
|
||||||
|
operationId: createPet
|
||||||
|
tags:
|
||||||
|
- pets
|
||||||
|
security:
|
||||||
|
- BearerAuth: []
|
||||||
|
- ApiKeyAuth: []
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/PetInput'
|
||||||
|
responses:
|
||||||
|
'201':
|
||||||
|
description: Pet created successfully
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Pet'
|
||||||
|
'400':
|
||||||
|
description: Invalid input
|
||||||
|
/pets/{petId}:
|
||||||
|
get:
|
||||||
|
summary: Get a pet by ID
|
||||||
|
description: Returns a single pet by its ID
|
||||||
|
operationId: getPetById
|
||||||
|
tags:
|
||||||
|
- pets
|
||||||
|
parameters:
|
||||||
|
- name: petId
|
||||||
|
in: path
|
||||||
|
description: ID of the pet to retrieve
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: A single pet
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Pet'
|
||||||
|
'404':
|
||||||
|
description: Pet not found
|
||||||
|
put:
|
||||||
|
summary: Update a pet
|
||||||
|
description: Updates an existing pet in the store
|
||||||
|
operationId: updatePet
|
||||||
|
tags:
|
||||||
|
- pets
|
||||||
|
security:
|
||||||
|
- BearerAuth: []
|
||||||
|
parameters:
|
||||||
|
- name: petId
|
||||||
|
in: path
|
||||||
|
description: ID of the pet to update
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/PetInput'
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Pet updated successfully
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Pet'
|
||||||
|
'404':
|
||||||
|
description: Pet not found
|
||||||
|
delete:
|
||||||
|
summary: Delete a pet
|
||||||
|
description: Deletes a pet from the store
|
||||||
|
operationId: deletePet
|
||||||
|
tags:
|
||||||
|
- pets
|
||||||
|
security:
|
||||||
|
- ApiKeyAuth: []
|
||||||
|
parameters:
|
||||||
|
- name: petId
|
||||||
|
in: path
|
||||||
|
description: ID of the pet to delete
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
responses:
|
||||||
|
'204':
|
||||||
|
description: Pet deleted successfully
|
||||||
|
'404':
|
||||||
|
description: Pet not found
|
||||||
|
/store/inventory:
|
||||||
|
get:
|
||||||
|
summary: Get store inventory
|
||||||
|
description: Returns pet inventory by status
|
||||||
|
operationId: getInventory
|
||||||
|
tags:
|
||||||
|
- store
|
||||||
|
security:
|
||||||
|
- ApiKeyAuth: []
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Inventory counts by status
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
additionalProperties:
|
||||||
|
type: integer
|
||||||
|
/users:
|
||||||
|
get:
|
||||||
|
summary: List all users
|
||||||
|
description: Returns a list of users
|
||||||
|
operationId: listUsers
|
||||||
|
tags:
|
||||||
|
- users
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: A list of users
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/User'
|
||||||
|
post:
|
||||||
|
summary: Create a user
|
||||||
|
description: Creates a new user
|
||||||
|
operationId: createUser
|
||||||
|
tags:
|
||||||
|
- users
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/UserInput'
|
||||||
|
responses:
|
||||||
|
'201':
|
||||||
|
description: User created successfully
|
||||||
|
|
||||||
|
components:
|
||||||
|
securitySchemes:
|
||||||
|
ApiKeyAuth:
|
||||||
|
type: apiKey
|
||||||
|
name: X-API-Key
|
||||||
|
in: header
|
||||||
|
BearerAuth:
|
||||||
|
type: http
|
||||||
|
scheme: bearer
|
||||||
|
bearerFormat: JWT
|
||||||
|
schemas:
|
||||||
|
Pet:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- name
|
||||||
|
- status
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
description: Unique identifier
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
description: Name of the pet
|
||||||
|
status:
|
||||||
|
type: string
|
||||||
|
enum:
|
||||||
|
- available
|
||||||
|
- pending
|
||||||
|
- sold
|
||||||
|
description: Status of the pet
|
||||||
|
tags:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
description: Tags associated with the pet
|
||||||
|
photoUrls:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
format: uri
|
||||||
|
description: URLs of pet photos
|
||||||
|
PetInput:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- name
|
||||||
|
- status
|
||||||
|
properties:
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
description: Name of the pet
|
||||||
|
status:
|
||||||
|
type: string
|
||||||
|
enum:
|
||||||
|
- available
|
||||||
|
- pending
|
||||||
|
- sold
|
||||||
|
description: Status of the pet
|
||||||
|
tags:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
User:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
username:
|
||||||
|
type: string
|
||||||
|
description: Unique username
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
firstName:
|
||||||
|
type: string
|
||||||
|
lastName:
|
||||||
|
type: string
|
||||||
|
UserInput:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- username
|
||||||
|
- email
|
||||||
|
properties:
|
||||||
|
username:
|
||||||
|
type: string
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
firstName:
|
||||||
|
type: string
|
||||||
|
lastName:
|
||||||
|
type: string
|
||||||
Reference in New Issue
Block a user