mirror of
https://github.com/LukeHagar/openapi-types.git
synced 2025-12-06 12:37:47 +00:00
76 lines
2.2 KiB
TypeScript
76 lines
2.2 KiB
TypeScript
import type { Extension } from "./extensions"
|
|
|
|
/**
|
|
* -----
|
|
* Example Object
|
|
* -----
|
|
*
|
|
* Allows sharing examples for operation responses. Examples provide concrete
|
|
* instances of what the API response will look like, making it easier for
|
|
* developers to understand the expected data structure and format.
|
|
*
|
|
* Examples are commonly used by documentation generators and API testing tools
|
|
* to provide realistic sample data that developers can use as a reference
|
|
* when implementing client applications.
|
|
*
|
|
* | Version | Reference |
|
|
* |---|-----|
|
|
* | 2.0 | {@link https://swagger.io/specification/v2/#example-object | Swagger 2.0 Example Object} |
|
|
*
|
|
* -----
|
|
* Fields
|
|
* -----
|
|
*
|
|
* @key `[mimeType]` - The name of the property MUST be one of the Operation produces values (either implicit or inherited). The value SHOULD be an example of what such a response would look like.
|
|
*
|
|
* @note
|
|
* The property names correspond to MIME types that the operation can produce.
|
|
*
|
|
* -----
|
|
* Examples
|
|
* -----
|
|
*
|
|
* @example (JSON response example):
|
|
* ```ts
|
|
* const example: Example = {
|
|
* "application/json": {
|
|
* "name": "Puma",
|
|
* "type": "Dog",
|
|
* "color": "Black",
|
|
* "gender": "Female",
|
|
* "breed": "Mixed"
|
|
* }
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (XML response example):
|
|
* ```ts
|
|
* const example: Example = {
|
|
* "application/xml": "<pet><name>Puma</name><type>Dog</type></pet>"
|
|
* };
|
|
* ```
|
|
*
|
|
* @example (multiple content types):
|
|
* ```ts
|
|
* const example: Example = {
|
|
* "application/json": { "id": 1, "name": "John" },
|
|
* "application/xml": "<user><id>1</id><name>John</name></user>"
|
|
* };
|
|
* ```
|
|
*/
|
|
export interface Example extends Extension {
|
|
/**
|
|
* The name of the property MUST be one of the Operation produces values
|
|
* (either implicit or inherited). The value SHOULD be an example of what
|
|
* such a response would look like.
|
|
*
|
|
* The property name corresponds to a MIME type that the operation can produce.
|
|
* The value should be a realistic example of the response data in that format.
|
|
*
|
|
* @example { "application/json": { name: "Puma", type: "Dog" } }
|
|
* @example { "application/xml": "<pet><name>Puma</name></pet>" }
|
|
* @example { "text/plain": "Success" }
|
|
*/
|
|
[mimeType: string]: unknown
|
|
}
|