### OpenAPI Documentation with Examples Source: https://context7.com/oai/learn.openapis.org/llms.txt Demonstrates using `summary` and `description` fields for API documentation, along with `example` and `examples` for providing sample data. This enhances clarity for developers and mock server generation. ```yaml openapi: 3.1.0 info: title: Audio Control API version: 1.0.0 description: | This API controls audio settings for the media player. ## Features - Volume control with overdrive support - Multiple audio profiles - Real-time adjustments paths: /audio/volume: put: summary: Set audio volume description: | Adjusts the current volume for all audio output. **Volume Levels:** - `0`: Mute (no audio output) - `1-10`: Normal range - `11`: Overdrive mode (use with caution!) When volume is set to 0, all other audio settings have no effect. requestBody: required: true content: application/json: schema: type: integer minimum: 0 maximum: 11 description: Volume level (0-11) examples: muted: summary: Muted description: Audio completely off value: 0 normal: summary: Normal listening description: Comfortable listening level value: 5 loud: summary: Maximum normal volume value: 10 overdrive: summary: Overdrive mode description: | Warning: May cause speaker damage! value: 11 responses: '200': description: Volume updated successfully content: application/json: schema: type: object properties: previousVolume: type: integer currentVolume: type: integer mode: type: string enum: [muted, normal, overdrive] example: previousVolume: 3 currentVolume: 5 mode: normal '400': description: Invalid volume level content: application/json: schema: type: object properties: error: type: string validRange: type: string example: error: "Volume must be between 0 and 11" validRange: "0-11" ``` -------------------------------- ### GET /users Source: https://context7.com/oai/learn.openapis.org/llms.txt Retrieves a list of users with support for pagination. ```APIDOC ## GET /users ### Description Retrieve a paginated list of users. ### Method GET ### Endpoint /users ### Parameters #### Query Parameters - **limit** (integer) - Optional - Maximum number of users to return - **offset** (integer) - Optional - Number of users to skip ### Response #### Success Response (200) - **users** (array) - List of user objects #### Response Example [ { "id": 1, "name": "John Doe" } ] ``` -------------------------------- ### GET /pets Source: https://context7.com/oai/learn.openapis.org/llms.txt Retrieves a paginated list of pets from the store. ```APIDOC ## GET /pets ### Description Returns a list of all pets available in the store, with optional pagination. ### Method GET ### Endpoint /pets ### Parameters #### Query Parameters - **limit** (integer) - Optional - Maximum number of items to return (max 100). ### Response #### Success Response (200) - **pets** (array) - An array of Pet objects. #### Response Example [ { "id": 1, "name": "Fluffy", "tag": "cat" } ] ``` -------------------------------- ### OpenAPI Example and Examples Fields Source: https://github.com/oai/learn.openapis.org/blob/main/specification/docs.md Illustrates the use of 'example' for single values and 'examples' for multiple named values in OpenAPI schemas and media types. These fields allow for automated processing by mock servers and enhanced documentation rendering. ```yaml schema: coordinate: type: integer minimum: 1 maximum: 3 example: 1 responses: "400": description: The provided parameters are incorrect content: text/html: schema: type: string examples: illegalCoordinates: value: "Illegal coordinates." notEmpty: value: "Square is not empty." invalidMark: value: "Invalid Mark (X or O)." ``` -------------------------------- ### Convert Schema Example to Examples Source: https://github.com/oai/learn.openapis.org/blob/main/upgrading/v3.0-to-v3.1.md Replaces the singular 'example' keyword with the plural 'examples' array to support multiple example values within a schema object. ```yaml # OpenAPI 3.0 type: string example: fedora ``` ```yaml # OpenAPI 3.1 type: string examples: - fedora ``` -------------------------------- ### Apply CommonMark Syntax for Documentation Source: https://github.com/oai/learn.openapis.org/blob/main/specification/docs.md Provides examples of CommonMark syntax for headings, emphasis, and lists to format documentation within description fields. ```markdown # Level 1 ## Level 2 ### Level 3 *Emphasis* **Strong Emphasis** ***Both*** - Item 1 - Item 2 - Item 2.1 ``` -------------------------------- ### Minimal OpenAPI Description Example Source: https://github.com/oai/learn.openapis.org/blob/main/specification/structure.md An example of a minimal OpenAPI Description in YAML format, demonstrating the required fields. ```APIDOC ## Minimal OpenAPI Description Structure To be entirely precise, a minimal OpenAPI Description (OAD) is a single JSON object containing fields adhering to the structure defined in the [OpenAPI Specification](https://spec.openapis.org/oas/latest) (OAS). The OAS structure is long and complex so this section just describes the minimal set of fields it must contain, while following pages give more details about specific objects. The [OpenAPI Map](https://openapi-map.apihandyman.io/) is a nice visual tool that can help familiarize the reader with this long specification. The root object in any OpenAPI Description is the [OpenAPI Object](https://spec.openapis.org/oas/latest#openapi-object), and only two of its fields are mandatory: `openapi` and `info`. Additionally, at least one of `paths`, `components` and `webhooks` is required. * `openapi` (**string**): This indicates the version of the OAS this OAD is using, e.g. "3.1.0". Using this field tools can check that the description correctly adheres to the specification. * `$self` (**string**, OpenAPI 3.2+): Provides the canonical URI for the document itself, used as the base URI for resolving relative references. This field is optional. * `info` ([Info Object](https://spec.openapis.org/oas/latest#info-object)): This provides general information about the API (like its description, author and contact information) but the only mandatory fields are `title` and `version`. * `title` (**string**): A human-readable name for the API, like "GitHub REST API", useful to keep API collections organized. * `version` (**string**): Indicates the version **of the API description** (not to be confused with the OAS version above). Tools can use this field to generate code that ensures that clients and servers are interacting through the same version of the API, for example. * `paths` ([Paths Object](https://spec.openapis.org/oas/latest#paths-object)): This describes all the **endpoints** of the API, including their parameters and all possible server responses. Server and client code can be generated from this description, along with its documentation.
Diagrams are used in this guide to show the relationship between the different objects.
Here's an example of a minimal OpenAPI Description: ```yaml openapi: 3.1.0 info: title: A minimal OpenAPI Description version: 0.0.1 paths: {} # No endpoints defined ``` This API is not very useful because it **defines no operations** (it has no endpoints). [The next page](paths) remedies that. ## Summary This page has shown that: * The syntax (language) used to write OpenAPI Descriptions can be **JSON**, **YAML** or **both**. * An OpenAPI Description is a JSON object including the fields described in the [OpenAPI Specification](https://spec.openapis.org/oas/latest). * Every OpenAPI Descriptions must contain an OpenAPI Object with at least the fields `openapi`, and `info`, and either `paths`, `components` or `webhooks`. [The following page](paths) describes the contents of the `paths` field so endpoints can be added to the above minimal snippet. ``` -------------------------------- ### GET /users Source: https://context7.com/oai/learn.openapis.org/llms.txt Retrieves a list of users with optional pagination parameters. ```APIDOC ## GET /users ### Description Retrieves a paginated list of users from the system. ### Method GET ### Endpoint /users ### Parameters #### Query Parameters - **limit** (integer) - Optional - Maximum number of items to return (1-100, default: 20) - **offset** (integer) - Optional - Number of items to skip (default: 0) ### Response #### Success Response (200) - **users** (array) - List of User objects #### Response Example [ { "id": 1, "email": "user@example.com", "name": "John Doe", "createdAt": "2023-10-27T10:00:00Z" } ] ``` -------------------------------- ### POST /users Source: https://context7.com/oai/learn.openapis.org/llms.txt Creates a new user in the system. ```APIDOC ## POST /users ### Description Create a new user record. ### Method POST ### Endpoint /users ### Request Body - **user** (object) - Required - The user object to create ### Request Example { "name": "Jane Doe" } ### Response #### Success Response (201) - **user** (object) - The created user object #### Response Example { "id": 2, "name": "Jane Doe" } ``` -------------------------------- ### POST /pets Source: https://context7.com/oai/learn.openapis.org/llms.txt Creates a new pet entry in the system. ```APIDOC ## POST /pets ### Description Adds a new pet to the store inventory. ### Method POST ### Endpoint /pets ### Request Body - **id** (integer) - Required - Unique identifier. - **name** (string) - Required - Name of the pet. - **tag** (string) - Optional - Category tag. ### Request Example { "id": 2, "name": "Rex", "tag": "dog" } ### Response #### Success Response (201) - **message** (string) - Confirmation of creation. ``` -------------------------------- ### GET /users/me Source: https://context7.com/oai/learn.openapis.org/llms.txt Retrieves the profile information for the currently authenticated user. ```APIDOC ## GET /users/me ### Description Retrieves the profile information for the currently authenticated user. Requires Bearer token or OAuth2 authentication. ### Method GET ### Endpoint /users/me ### Parameters None ### Request Example N/A (Authentication header required) ### Response #### Success Response (200) - **id** (string) - Unique user identifier - **email** (string) - User email address #### Response Example { "id": "user_123", "email": "user@example.com" } ``` -------------------------------- ### GET /users/{id} Source: https://github.com/oai/learn.openapis.org/blob/main/specification/parameters.md Example of a path parameter used to identify a specific user resource. ```APIDOC ## GET /users/{id} ### Description Retrieves a specific user by their unique identifier provided in the URL path. ### Method GET ### Endpoint /users/{id} ### Parameters #### Path Parameters - **id** (string) - Required - The unique identifier of the user. ### Request Example N/A ### Response #### Success Response (200) - **user** (object) - The user resource details. #### Response Example { "id": "1234", "name": "John Doe" } ``` -------------------------------- ### GET /users Source: https://github.com/oai/learn.openapis.org/blob/main/specification/parameters.md Example of a query parameter used to filter or identify resources via the query string. ```APIDOC ## GET /users ### Description Retrieves a list of users, optionally filtered by an ID provided in the query string. ### Method GET ### Endpoint /users ### Parameters #### Query Parameters - **id** (string) - Optional - The unique identifier to filter users by. ### Request Example GET /users?id=1234 ### Response #### Success Response (200) - **users** (array) - A list of user objects. #### Response Example [ { "id": "1234", "name": "John Doe" } ] ``` -------------------------------- ### Configure multi-environment API servers Source: https://context7.com/oai/learn.openapis.org/llms.txt Shows how to define multiple server URLs for different environments and use server variables to create dynamic, templated base URLs for flexible API deployment. ```yaml openapi: 3.1.0 info: title: Multi-Environment API version: 1.0.0 servers: - url: https://api.example.com/v1 description: Production server - url: https://staging-api.example.com/v1 description: Staging environment for testing - url: http://localhost:3000/v1 description: Local development server - url: https://{username}.api.example.com:{port}/{version} description: Custom user server variables: username: default: demo description: Username assigned by the service provider port: enum: - "8443" - "443" default: "8443" description: Server port version: default: v1 description: API version paths: /status: get: summary: Get API status responses: '200': description: API is running content: application/json: schema: type: object properties: status: type: string environment: type: string ``` -------------------------------- ### Markdown Formatting Syntax Source: https://github.com/oai/learn.openapis.org/blob/main/specification/docs.md Demonstrates standard CommonMark syntax for creating inline code spans, fenced code blocks, hyperlinks, and images within documentation fields. ```markdown An inline `code span`. ``` A fenced code block ``` [Link text](Link URL) ![Alt text](Image URL) ``` -------------------------------- ### API Key Security Scheme Example Source: https://github.com/oai/learn.openapis.org/blob/main/specification/security.md This example demonstrates how to define an API Key security scheme in OpenAPI, specifying the header name for the API key. ```APIDOC ## API Key Security Scheme ### Description Defines an API key security scheme where the key is provided in an HTTP header. ### Method N/A (Schema Definition) ### Endpoint N/A (Schema Definition) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```yaml components: securitySchemes: defaultApiKey: description: API key provided in console type: apiKey name: api-key in: header ``` ### Response #### Success Response (200) N/A (Schema Definition) #### Response Example N/A (Schema Definition) ``` -------------------------------- ### Complete Enhanced Tags Example (OpenAPI 3.2) Source: https://github.com/oai/learn.openapis.org/blob/main/specification/tags.md A comprehensive example of enhanced tag usage in OpenAPI 3.2, showcasing hierarchical organization, summary fields, kind classification, and external documentation links for a bakery API. ```yaml openapi: 3.2.0 info: title: Bakery API version: 2.0.0 tags: # Main navigation categories - name: products summary: Products description: All bakery product operations kind: nav - name: orders summary: Orders description: Order management and tracking kind: nav # Product subcategories - name: cakes summary: Cakes description: Custom cakes and layer cakes parent: products kind: nav - name: breads summary: Breads description: Artisan breads and rolls parent: products kind: nav # Special categories - name: seasonal summary: Seasonal description: Limited-time seasonal offerings kind: badge externalDocs: description: Seasonal menu planning url: https://docs.bakery.com/seasonal paths: /cakes: get: tags: [cakes] summary: List available cakes /cakes/seasonal: get: tags: [cakes, seasonal] summary: List seasonal cake offerings /orders/wholesale: post: tags: [orders, wholesale] summary: Create wholesale order ``` -------------------------------- ### Define Parameter Descriptions in OpenAPI Source: https://github.com/oai/learn.openapis.org/blob/main/specification/docs.md Demonstrates how to add a descriptive field to an OpenAPI parameter schema to provide context beyond the machine-readable type definitions. ```yaml paths: /audio/volume: put: requestBody: required: true content: application/json: schema: type: integer minimum: 0 maximum: 11 description: | Current volume for all audio output. 0 means no audio output (mute). 10 is the maximum value. 11 enables the overdrive system (danger!). When set to 0 all other audio settings have no effect. ``` -------------------------------- ### Modularize OpenAPI Definitions with External References Source: https://context7.com/oai/learn.openapis.org/llms.txt Illustrates the use of $ref to split large API descriptions into smaller, maintainable files. This approach enables component reuse across paths, schemas, and parameters. ```yaml openapi: 3.1.0 info: title: Large Enterprise API paths: /users: $ref: './paths/users.yaml' components: schemas: User: $ref: './schemas/user.yaml' parameters: $ref: './parameters/common.yaml' ``` -------------------------------- ### Path Parameter Example in YAML Source: https://github.com/oai/learn.openapis.org/blob/main/specification/parameters.md Demonstrates how to define a path parameter named 'id' for a GET operation in YAML. Path parameters are mandatory and must be included in the URL path as a template expression. ```yaml paths: /users/{id}: get: parameters: - name: id in: path required: true ``` -------------------------------- ### Transform OpenAPI Documents using Overlay Specification Source: https://context7.com/oai/learn.openapis.org/llms.txt Shows how to use overlay files to inject metadata, license information, or gateway-specific configurations into an existing OpenAPI document without modifying the original source. ```yaml # overlay.yaml - Add license information overlay: 1.0.0 actions: - target: $.info update: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html ``` ```yaml # overlay-gateway.yaml - Add gateway-specific configuration overlay: 1.0.0 actions: - target: $.paths[*][*] update: x-gateway-rate-limit: 1000 x-gateway-timeout: 30000 ``` -------------------------------- ### Define Hierarchical Tags in OpenAPI 3.2 Source: https://context7.com/oai/learn.openapis.org/llms.txt This example demonstrates how to define a tag hierarchy using the 'parent' property and classify tags using 'kind'. It shows how these tags are applied to path operations to create a structured API documentation layout. ```yaml openapi: 3.2.0 info: title: Bakery API version: 2.0.0 tags: - name: products summary: Products description: All bakery product operations kind: nav - name: orders summary: Orders description: Order management and tracking kind: nav - name: cakes summary: Cakes description: Custom cakes and layer cakes parent: products kind: nav - name: breads summary: Breads description: Artisan breads and rolls parent: products kind: nav - name: seasonal-cakes summary: Seasonal description: Limited-time seasonal cake offerings parent: cakes - name: seasonal summary: Seasonal description: Limited-time seasonal offerings kind: badge - name: wholesale summary: Wholesale description: Bulk ordering available kind: badge paths: /cakes: get: tags: [cakes] summary: List available cakes responses: '200': description: List of cakes /cakes/seasonal: get: tags: [cakes, seasonal] summary: List seasonal cake offerings responses: '200': description: Seasonal cakes /orders/wholesale: post: tags: [orders, wholesale] summary: Create wholesale order responses: '201': description: Wholesale order created ``` -------------------------------- ### Mix JSON and YAML syntax in OpenAPI Source: https://github.com/oai/learn.openapis.org/blob/main/specification/structure.md Shows an example of using abbreviated array syntax within a YAML document, demonstrating how YAML can incorporate JSON-like structures. ```yaml anObject: aString: "This is a string" arrayOfNumbers: [ 1, 2, 3 ] # Abbreviated array representation ``` -------------------------------- ### QUERY /products Source: https://context7.com/oai/learn.openapis.org/llms.txt Perform advanced product searches using the QUERY HTTP method with structured filter, sort, and pagination options in the request body. ```APIDOC ## QUERY /products ### Description Use the QUERY method for complex searches that don't fit in URL query strings. The request body contains structured filter, sort, and pagination options. ### Method QUERY ### Endpoint /products ### Parameters #### Request Body - **filter** (object) - Required - Object containing search filters. - **category** (string) - Optional - Filter by product category. - **priceRange** (object) - Optional - Filter by price range. - **min** (number) - Optional - Minimum price. - **max** (number) - Optional - Maximum price. - **inStock** (boolean) - Optional - Filter by stock availability. - **sort** (array) - Optional - Array of sort criteria. - **field** (string) - Required - Field to sort by. - **direction** (string) - Required - Sort direction (`asc` or `desc`). - **pagination** (object) - Optional - Pagination settings. - **page** (integer) - Required - Page number. - **pageSize** (integer) - Required - Number of items per page. ### Request Example ```json { "filter": { "category": "electronics", "priceRange": { "min": 100, "max": 500 }, "inStock": true }, "sort": [ { "field": "price", "direction": "asc" } ], "pagination": { "page": 1, "pageSize": 20 } } ``` ### Response #### Success Response (200) - **results** (array) - Array of product objects matching the search criteria. - **totalCount** (integer) - Total number of products found. - **page** (integer) - Current page number. #### Response Example ```json { "results": [ { "id": "prod_123", "name": "Example Product", "price": 150.00 } ], "totalCount": 150, "page": 1 } ``` ``` -------------------------------- ### Reuse API components with $ref Source: https://context7.com/oai/learn.openapis.org/llms.txt Demonstrates how to define schemas, parameters, and responses within the components object and reference them throughout the API paths. This approach minimizes code duplication and ensures consistency across the API definition. ```yaml openapi: 3.1.0 info: title: Component Reuse Example version: 1.0.0 paths: /users: get: summary: List users parameters: - $ref: '#/components/parameters/limitParam' - $ref: '#/components/parameters/offsetParam' responses: '200': description: Successful response content: application/json: schema: type: array items: $ref: '#/components/schemas/User' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalError' /users/{userId}: get: summary: Get user by ID parameters: - $ref: '#/components/parameters/userIdParam' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/User' '404': $ref: '#/components/responses/NotFound' components: schemas: User: type: object required: - id - email properties: id: type: integer format: int64 email: type: string format: email name: type: string createdAt: type: string format: date-time Error: type: object required: - code - message properties: code: type: integer message: type: string details: type: string parameters: limitParam: name: limit in: query description: Maximum number of items to return schema: type: integer minimum: 1 maximum: 100 default: 20 offsetParam: name: offset in: query description: Number of items to skip schema: type: integer minimum: 0 default: 0 userIdParam: name: userId in: path required: true description: Unique user identifier schema: type: integer format: int64 responses: BadRequest: description: Bad request - invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' ``` -------------------------------- ### Define API Endpoints and Operations Source: https://context7.com/oai/learn.openapis.org/llms.txt Illustrates how to define API paths, HTTP methods, parameters, and request/response bodies. It also demonstrates the use of component schemas for data modeling and reusability. ```yaml openapi: 3.1.0 info: title: Pet Store API version: 1.0.0 servers: - url: http://petstore.swagger.io/v1 paths: /pets: get: summary: List all pets operationId: listPets tags: - pets parameters: - name: limit in: query description: Maximum number of items to return (max 100) required: false schema: type: integer maximum: 100 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: type: array items: $ref: '#/components/schemas/Pet' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' post: summary: Create a pet operationId: createPet tags: - pets requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Pet' responses: '201': description: Pet created successfully default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /pets/{petId}: get: summary: Get 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' 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 Error: type: object required: - code - message properties: code: type: integer format: int32 message: type: string ``` -------------------------------- ### Configure Path Parameters and Request Bodies Source: https://context7.com/oai/learn.openapis.org/llms.txt Illustrates how to define path parameters for coordinate-based endpoints and request bodies for state-changing operations in an OpenAPI 3.1.0 specification. ```yaml openapi: 3.1.0 info: title: Tic Tac Toe API version: 1.0.0 paths: /board/{row}/{column}: parameters: - name: row in: path required: true description: Board row (vertical coordinate) schema: type: integer minimum: 1 maximum: 3 - name: column in: path required: true description: Board column (horizontal coordinate) schema: type: integer minimum: 1 maximum: 3 get: summary: Get a single board square description: Retrieves the requested square. responses: '200': description: OK content: application/json: schema: type: string enum: [".", "X", "O"] '400': description: The provided parameters are incorrect content: text/html: schema: type: string example: "Illegal coordinates" put: summary: Set a single board square description: Places a mark on the board requestBody: required: true content: application/json: schema: type: string enum: [".", "X", "O"] example: "X" responses: '200': description: OK content: application/json: schema: type: object properties: winner: type: string enum: [".", "X", "O"] board: type: array items: type: array items: type: string enum: [".", "X", "O"] '400': description: The provided parameters are incorrect content: text/html: schema: type: string examples: illegalCoordinates: value: "Illegal coordinates." notEmpty: value: "Square is not empty." invalidMark: value: "Invalid Mark (X or O)." ``` -------------------------------- ### Define Path Item Objects Source: https://github.com/oai/learn.openapis.org/blob/main/specification/paths.md Shows how to define HTTP methods like GET and PUT within a specific path item object to describe available operations. ```yaml paths: /board: get: ... put: ... ``` -------------------------------- ### Use Literal and Folded YAML String Modes Source: https://github.com/oai/learn.openapis.org/blob/main/specification/docs.md Illustrates the use of literal (|) and folded (>) indicators in YAML to control how line breaks are handled in multi-line strings. ```yaml # Literal mode preserves line breaks description: | This is a string in multiple lines. And an extra one. # Folded mode converts line breaks to spaces description: > This is a string in multiple lines. And an extra one. ``` -------------------------------- ### Define Minimal OpenAPI Description Structure Source: https://context7.com/oai/learn.openapis.org/llms.txt Demonstrates the mandatory fields required for a valid OpenAPI document, including the version, info object, and paths. This structure serves as the foundation for any API description. ```yaml openapi: 3.1.0 info: title: My First API description: | This API demonstrates the minimal structure required for a valid OpenAPI Description document. version: 1.0.0 paths: /health: get: summary: Health check endpoint description: Returns the API health status responses: "200": description: API is healthy content: application/json: schema: type: object properties: status: type: string example: "healthy" timestamp: type: string format: date-time ``` -------------------------------- ### GET /status Source: https://context7.com/oai/learn.openapis.org/llms.txt Checks the operational status and environment of the API server. ```APIDOC ## GET /status ### Description Returns the current health status and environment context of the API. ### Method GET ### Endpoint /status ### Response #### Success Response (200) - **status** (string) - Current status of the API - **environment** (string) - The environment name (e.g., production, staging) #### Response Example { "status": "running", "environment": "production" } ``` -------------------------------- ### GET /pets/{petId} Source: https://context7.com/oai/learn.openapis.org/llms.txt Retrieves details for a specific pet by its unique identifier. ```APIDOC ## GET /pets/{petId} ### Description Fetches the details of a specific pet using the pet's ID. ### Method GET ### Endpoint /pets/{petId} ### Parameters #### Path Parameters - **petId** (string) - Required - The unique identifier of the pet. ### Response #### Success Response (200) - **id** (integer) - Pet ID. - **name** (string) - Pet name. - **tag** (string) - Pet tag. #### Response Example { "id": 1, "name": "Fluffy", "tag": "cat" } ``` -------------------------------- ### GET /users/{userId} Source: https://context7.com/oai/learn.openapis.org/llms.txt Retrieves detailed information for a specific user by their unique identifier. ```APIDOC ## GET /users/{userId} ### Description Fetches a single user profile based on the provided user ID. ### Method GET ### Endpoint /users/{userId} ### Parameters #### Path Parameters - **userId** (integer) - Required - Unique user identifier ### Response #### Success Response (200) - **id** (integer) - User ID - **email** (string) - User email - **name** (string) - User name - **createdAt** (string) - Creation timestamp #### Response Example { "id": 1, "email": "user@example.com", "name": "John Doe", "createdAt": "2023-10-27T10:00:00Z" } ``` -------------------------------- ### GET /health Source: https://context7.com/oai/learn.openapis.org/llms.txt A basic health check endpoint demonstrating the minimal structure of an OpenAPI path definition. ```APIDOC ## GET /health ### Description Returns the current health status of the API. ### Method GET ### Endpoint /health ### Response #### Success Response (200) - **status** (string) - The health status of the service. - **timestamp** (string) - The ISO 8601 formatted timestamp of the check. #### Response Example { "status": "healthy", "timestamp": "2023-10-27T10:00:00Z" } ``` -------------------------------- ### GET /board/{row}/{column} Source: https://context7.com/oai/learn.openapis.org/llms.txt Retrieves the content of a single board square on the Tic Tac Toe board. It takes row and column coordinates as path parameters. ```APIDOC ## GET /board/{row}/{column} ### Description Retrieves the requested square on the Tic Tac Toe board. ### Method GET ### Endpoint /board/{row}/{column} ### Parameters #### Path Parameters - **row** (integer) - Required - Board row (vertical coordinate). Must be between 1 and 3. - **column** (integer) - Required - Board column (horizontal coordinate). Must be between 1 and 3. ### Response #### Success Response (200) - **(string)** - The content of the square, which can be '.', 'X', or 'O'. #### Response Example ```json "." ``` #### Error Response (400) - **(string)** - Description of the error, e.g., "Illegal coordinates". #### Response Example ```html Illegal coordinates ``` ``` -------------------------------- ### Define basic server list in OpenAPI Source: https://github.com/oai/learn.openapis.org/blob/main/specification/servers.md Demonstrates how to define multiple server URLs within the root servers array, including optional descriptions for each environment. ```yaml servers: - url: https://europe.server.com/v1 description: Server located in Germany. - url: https://america.server.com/v1 description: Server located in Atlanta, GA. - url: https://asia.server.com/v1 description: Server located in Shenzhen ``` -------------------------------- ### Query Parameter Example in YAML Source: https://github.com/oai/learn.openapis.org/blob/main/specification/parameters.md Illustrates how to define a query parameter named 'id' for a GET operation in YAML. Query parameters are appended to the URL's query string. ```yaml paths: /users: get: parameters: - name: id in: query ``` -------------------------------- ### Add parameters to operations with x-supports-filters: true (YAML) Source: https://github.com/oai/learn.openapis.org/blob/main/overlay/example-add-filter-parameters.md This YAML snippet defines an OpenAPI overlay action. It targets operations where the `x-supports-filters` extension is true and adds two query parameters ('month' and 'time_start') along with an `x-filters-added` tag. This is useful for applying common parameter sets consistently. ```yaml overlay: 1.0.0 info: title: Add filter parameters everywhere version: 1.0.0 actions: - target: $.paths.*.*[?(@.x-supports-filters == true)] update: parameters: - name: month in: query description: Month number of event (1-12) required: false type: integer - name: time_start in: query description: Start time of event required: false type: string tags: - x-filters-added ``` -------------------------------- ### Copy Schema Component using OpenAPI Overlay Source: https://github.com/oai/learn.openapis.org/blob/main/overlay/example-copy-schema.md This YAML snippet defines an OpenAPI overlay action to copy an existing schema component. It first ensures the target schema ('Bar') exists and then copies the content from the source schema ('Foo') to the target. ```yaml overlay: 1.1.0 info: title: Copy a schema component version: 1.1.0 actions: - target: '$.components.schemas' description: Ensure the target schema is present update: Bar: {} - target: '$.components.schemas['Bar']' copy: '$.components.schemas['Foo']' description: Copy the Foo Schema to Bar ``` -------------------------------- ### Reference OpenID Connect Security Scheme with Scopes (YAML) Source: https://github.com/oai/learn.openapis.org/blob/main/specification/security.md This example demonstrates how to reference a defined OpenID Connect security scheme within the `security` section of an OpenAPI document. It shows how to apply specific scopes, such as 'board:read' and 'board:write', which are expected to be defined in the discovery endpoint. ```yaml openapi: 3.1.0 info: title: Tic Tac Toe description: | This API allows writing down marks on a Tic Tac Toe board and requesting the state of the board or of individual squares. version: 1.0.0 security: - openIdConnect: - board:read - board:write ``` -------------------------------- ### Applying Global and Operation-Specific Security Source: https://github.com/oai/learn.openapis.org/blob/main/specification/security.md Illustrates how to apply a defined security scheme globally to an API and also specifically to an individual operation. ```APIDOC ## Applying Security Schemes ### Description Shows how to apply a defined security scheme globally to an entire API and also to a specific operation. ### Method N/A (Schema Definition) ### Endpoint N/A (Schema Definition) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```yaml openapi: 3.1.0 info: title: Tic Tac Toe description: | This API allows writing down marks on a Tic Tac Toe board and requesting the state of the board or of individual squares. version: 1.0.0 security: - defaultApiKey: [] paths: /board: get: security: - defaultApiKey: [] ``` ### Response #### Success Response (200) N/A (Schema Definition) #### Response Example N/A (Schema Definition) ``` -------------------------------- ### GET /cakes Source: https://github.com/oai/learn.openapis.org/blob/main/specification/tags.md Retrieves a list of available cakes, categorized under the 'cakes' tag. ```APIDOC ## GET /cakes ### Description List all available cakes in the catalog. ### Method GET ### Endpoint /cakes ### Response #### Success Response (200) - **cakes** (array) - A list of available cake objects. #### Response Example { "cakes": [ { "id": 1, "name": "Chocolate Fudge" }, { "id": 2, "name": "Vanilla Bean" } ] } ``` -------------------------------- ### PUT /audio/volume Source: https://context7.com/oai/learn.openapis.org/llms.txt Adjusts the current volume level for the media player, supporting standard and overdrive modes. ```APIDOC ## PUT /audio/volume ### Description Adjusts the current volume for all audio output. Supports values from 0 (mute) to 11 (overdrive). ### Method PUT ### Endpoint /audio/volume ### Request Body - **volume** (integer) - Required - Volume level (0-11) ### Request Example { "volume": 5 } ### Response #### Success Response (200) - **previousVolume** (integer) - The volume level before the update - **currentVolume** (integer) - The new volume level - **mode** (string) - The current mode (muted, normal, overdrive) #### Response Example { "previousVolume": 3, "currentVolume": 5, "mode": "normal" } ``` -------------------------------- ### GET /dashboard Source: https://github.com/oai/learn.openapis.org/blob/main/specification/parameters.md Retrieves dashboard preferences using cookie-based parameter serialization. ```APIDOC ## GET /dashboard ### Description Retrieves user dashboard settings by reading preferences from a cookie. ### Method GET ### Endpoint /dashboard ### Parameters #### Query Parameters - **preferences** (object) - Optional - Cookie-based parameter containing theme and language settings. ### Request Example Cookie: preferences={ "theme": "dark", "language": "en" } ### Response #### Success Response (200) - **theme** (string) - The user's selected theme. - **language** (string) - The user's selected language. #### Response Example { "theme": "dark", "language": "en" } ``` -------------------------------- ### Additional Operations for /documents/{id} Source: https://context7.com/oai/learn.openapis.org/llms.txt Manage relationships between documents using custom HTTP methods LINK and UNLINK. ```APIDOC ## LINK /documents/{id} ### Description Creates a relationship between two documents. ### Method LINK ### Endpoint /documents/{id} ### Parameters #### Path Parameters - **id** (string) - Required - The ID of the document to link from. #### Request Body - **targetDocument** (string) - Required - The ID of the document to link to. - **relationship** (string) - Required - The type of relationship (`related`, `parent`, `child`, `reference`). ### Response #### Success Response (204) Indicates the link was created successfully. ## UNLINK /documents/{id} ### Description Removes a link between two documents. ### Method UNLINK ### Endpoint /documents/{id} ### Parameters #### Path Parameters - **id** (string) - Required - The ID of the document to unlink from. #### Request Body - **targetDocument** (string) - Required - The ID of the document to unlink to. ### Response #### Success Response (204) Indicates the link was removed successfully. ``` -------------------------------- ### Define Server Variables in OpenAPI Source: https://github.com/oai/learn.openapis.org/blob/main/specification/servers.md Demonstrates the syntax for defining server URL templates with curly braces and providing the corresponding Server Variable Objects to define defaults and allowed values. ```yaml servers: - url: https://{username}.server.com:{port}/{version} variables: username: default: demo description: This value is assigned by the service provider. port: enum: - "8443" - "443" default: "8443" version: default: v1 ``` -------------------------------- ### GET /board Source: https://github.com/oai/learn.openapis.org/blob/main/specification/content.md Retrieves the current state of the Tic Tac Toe board, including the current winner and the 3x3 grid configuration. ```APIDOC ## GET /board ### Description Retrieves the current state of the board and the winner. ### Method GET ### Endpoint /board ### Response #### Success Response (200) - **winner** (string) - Winner of the game. "." means nobody has won yet, "X" or "O" for the winner. - **board** (array) - A 3x3 matrix representing the board, where each element is a string (".", "X", or "O"). #### Response Example { "winner": ".", "board": [ [".", ".", "."], [".", "X", "."], [".", ".", "O"] ] } ``` -------------------------------- ### Construct endpoint URLs from server base Source: https://github.com/oai/learn.openapis.org/blob/main/specification/servers.md Illustrates how the final API endpoint is constructed by appending the path to the defined server base URL. ```yaml servers: - url: https://server.com/v1 paths: /users: get: ```