OpenAPI 3.0 Domain Example
Below is an example of an OpenAPI 3.0 domain definition demonstrating various types of domain components.
See also: OpenAPI 2.0 Domain Example and AsyncAPI Domain Example
# OpenAPI version identifier - required for OpenAPI 3.0 domains openapi: 3.0.0 ####################### # Optional info section ####################### info: title: Acme Components description: Common components for Acme REST APIs version: 1.0.0 components: #################### # Common data models #################### schemas: ErrorModel: type: object required: - code - message properties: code: type: integer format: int32 message: type: string #################### # Common parameters #################### parameters: offsetParam: name: offset in: query schema: type: integer minimum: 0 description: The number of items to skip before returning the results limitParam: in: query name: limit schema: type: integer format: int32 minimum: 1 maximum: 100 default: 20 description: The number of items to return ####################### # Common request bodies ####################### requestBodies: NewItem: description: A JSON object containing item data required: true content: application/json: schema: type: object examples: tshirt: $ref: '#/components/examples/tshirt' #################### # Common responses #################### responses: GeneralError: description: An error occurred content: application/json: schema: $ref: '#/components/schemas/ErrorModel' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' ######################### # Common headers # (except request headers - they are defined as parameters) ######################### headers: X-RateLimit-Limit: description: Request limit per hour schema: type: integer example: 100 X-RateLimit-Remaining: description: Remaining requests for the hour schema: type: integer example: 94 ####################### # Common path items ####################### pathitems: EntityOperations: get: summary: Get all items description: This operation supports pagination parameters: - $ref: '#/components/parameters/offsetParam' - $ref: '#/components/parameters/limitParam' responses: '200': description: A list of items headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' default: $ref: '#/components/responses/GeneralError' post: summary: Add a new item requestBody: $ref: '#/components/requestBodies/NewItem' responses: '201': description: Created headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' ###################################### # Common examples of input/output data ###################################### examples: tshirt: summary: Sample T-shirt data value: # Example value starts here id: 17 name: T-shirt description: 100% cotton shirt categories: [clothes] ######################### # Common link definitions # See: https://swagger.io/docs/specification/links/ ######################### links: {} ######################### # Common callback definitions # See: https://swagger.io/docs/specification/callbacks/ ######################### callbacks: {}