- Notifications
You must be signed in to change notification settings - Fork 83
Static File Samples
The Callback annotation represents a callback URL that will be invoked.
callback: name: myCallback callBackUrlExpression: www.myurl.com callbackOperation: method: POSTThe Callbacks annotation represents an array of Callback URLs that can be invoked.
callbacks: value: name: myCallback callBackUrlExpression: www.myurl.com callbackOperation: method: POSTThe CallbackOperation annotation represents an operation that will be invoked during the callback.
callbackOperation: method: POST summary: A Brief Description Of What The MethodDoes description: A verbose description of the callback operation behavior externalDocs: description: A short description of the target documentation. url: www.urlfortargetdocumentation.com parameters: name: parameterName requestBody: name: requestBodyName description: A brief description of the request body responses: responseCode: '202' security: name: oauth2 scopes: read:reviews extension: name: xHeader value: extensionValThe Components annotation is a container that holds various reusable objects for different aspects of the OpenAPI Specification.
components: schemas: name: schemaName responses: responseCode: '200' parameter: name: parameterName examples: name: exampleName requestBodies: description: A brief description headers: name: headerName securitySchemes: securitySchemeName: oauth2 links: name: linkName server: url: www.link.com callbacks: name: myCallbackThe Extension annotation adds an extension with contained properties.
extension: name: xHeader value: extensionValxThe Extensions annotation adds custom properties to an extension.
extensions: - name: xHeader value: extensionValx - name: yHeader value: extensionValyThe ExternalDocumentation annotation references an external resource for extended documentation.
externalDocumentation: description: A short description of the target documentation url: www.urlfortargetdocumentation.comThe Header annotation describes a single header object.
header: name: headerName description: the header's description schema: name: schemaName required: true deprecated: false allowEmptyValue: trueThe Contact annotation describes the contact information for the exposed API.
contact: name: contactName url: www.urlofcontact.com email: mycontact@email.comThe Info annotation encapsulates metadata about the API.
info: title: My Application Title description: My applicatoin description termsOfService: My application's terms of service contact: name: contactName url: www.urlofcontact.com email: mycontact@email.com license: name: licenseName version: '2.0.1'The License annotation describes the license information for the exposed API.
license: name: licenseName url: www.myurlformylicense.comThe Link annotation represents a design-time link for a response.
link: name: linkName operationRef: an operation ref parameters: name: the parameter's name description: the link's description requestBody: requestBody of the link server: url: www.serverurl.com/v1/{myServerVariable1}/{myServerVariable1} variables: name: myServerVariable1 defaultValue: RACHThe LinkParameter annotation represents a parameter to pass to the linked operation.
linkParameter: name: linkParameterName expression: the parameter's literal value or expressionThe Content annotation provides schema and examples for a particular media type.
content: mediaType: application/x-www-form-urlencoded examples: name: exampleObjectName schema: name: schemaName encoding: name: encodingNameThe DiscriminatorMapping used to differentiate between other schemas which may satisfy the payload description.
discriminatorMapping: value: the property value that gets mapped to schema schema: name: schemaNameThe Encoding annotation describes a single encoding definition to be applied to single Schema Object.
encoding: name: encodingName contentStyle: text/plain explode: true allowReserved: true headers: name: headerNameThe ExampleObject annotation illustrates an example of a particular content.
exampleProject: name: Example object name summary: a summary of this example description: a description of this example value: the value of the exampleThe Schema annotation allows the definition of input and output data types.
schema: name: myMusic title: get all music description: POJO that represents a music collection implementation: Review not: Movie oneOf: Music anyOf: - Artists - Albums - Genre allOf: - Artists - Albums - Genre multipleOf: 2.0 maximum: '100000' exclusiveMaximum: true minimum: '0' exclusiveMnimimum: false maxLength: 1000000 minLength: 2 pattern: "" maxProperties: 0 minProperties: 0 requitedProperties: - lat - long required: false format: int32 nullable: true readOnly: true writeOnly: false example: provide an example of how this Schema can be used, cannot be naturally represented in JSON or YAML externalDocs: - url: www.url.com description: This is the description deprecated: false type: array enumeration: - Rachel - Tommy - Jana - Anna defaultValue: Rachel discriminatorProperty: music_type discriminatorMapping: value: indie schema: title: indieMusic hidden: false maxItems: 500 minItems: 0 uniqueItems: falseThe OpenAPIDefinition annotation provides general metadata for an OpenAPI definition.
openAPIDefinition: info: title: Music Title contact: name: Mr.X email: mrxyzufo@xxx.com version: '3.0.0' tags: name: MusicType servers: url: www.serverurl.com/v1 security: name: oauth2 scopes: read:reviews externalDocs: url: www.externaldocurl.com description: url used for external documents components: schema: title: MusicThe Operation annotation describes an operation or typically a HTTP method against a specific path.
operation: operationId: getAllSongs summary: get all of the classified songs description: This operation retrieves songs from the hidden database deprecated: false hidden: trueThe Parameter annotation describes a single operation parameter.
parameter: name: musicAlbums in: path description: name of the music albums for reviews required: true deprecated: false allowEmptyValue: false style: label explode: false allowReserved: false schema: title: Music content: schema: $ref: '#/components/schemas/requestBody' hidden: false examples: - '1989' - 'reputation' example: BabyThe Parameters annotation encapsulates input parameters.
parameters: value: - name: musicAlbums - name: artistsThe RequestBody annotation describes a single request body.
requestBody: name: requestBodyName description: A brief description of the request body content: schema: $ref: '#/components/schemas/requestBody' required: true encoding: name: name of this encoding instanceThe APIResponse annotation describes a single response from an API operation.
APIResponse: responseCode: '200' name: APIResponsetoMusic description: A simple array response headers: $ref: '#/components/headers/APIResponse' links: $ref: '#/components/links/APIResponse' content: schema: $ref: '#/components/schemas/APIResponse'The APIResponses annotation acts as a container for multiple responses from an API operation.
APIResponses: value: - responseCode: '201' description: A simple array response - responseCode: '202' description: A complex array responseThe OAuthFlow annotation defines the configuration details for a supported OAuth Flow.
OAuthFlow: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token refreshUrl: https://example.com/api/oauth/newtoken scopes: name: read:reviews description: read some reviewsThe OAuthFlows annotation allows configuration of the supported OAuth Flows.
OAuthFlows: implicit: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token refreshUrl: https://example.com/api/oauth/newtoken scopes: name: read:reviews description: read some reviews passwords: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token refreshUrl: https://example.com/api/oauth/newtoken scopes: name: read:reviews description: read some reviews clientCredentials: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token refreshUrl: https://example.com/api/oauth/newtoken scopes: name: read:reviews description: read some reviews authorizationCode: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token refreshUrl: https://example.com/api/oauth/newtoken scopes: name: read:reviews description: read some reviewsThe OAuthScope annotation represents an OAuth scope.
OAuthScope: name: read:reviews description: read some reviewsThe SecurityRequirement annotation specifies a security requirement for an operation.
securityRequirement: name: oauth2 scopes: read:reviewsThe SecurityRequirements annotation represents an array of security requirements where only one needs to be satisfied.
securityRequirements: - name: api_key scopes: read:reviews - name: oauth2 scopes: read:reviewsThe SecurityRequirementsSet annotation represents an array of security requirements that need to be satisfied.
securityRequirementSet: - name: api_key scopes: read:reviews - name: oauth2 scopes: read:reviewsThe SecurityScheme annotation defines a security scheme that can be used by the operations.
securityScheme: securitySchemeName: oauth2 type: oauth2 description: Authentication needed for this operation flows: implicit: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token refreshUrl: https://example.com/api/oauth/newtoken scopes: name: read:reviews description: read some reviews passwords: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token refreshUrl: https://example.com/api/oauth/newtoken scopes: name: read:reviews description: read some reviews clientCredentials: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token refreshUrl: https://example.com/api/oauth/newtoken scopes: name: read:reviews description: read some reviews authorizationCode: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token refreshUrl: https://example.com/api/oauth/newtoken scopes: name: read:reviews description: read some reviewsThe SecuritySchemes annotation represents an array of security schemes that can be specified.
securitySchemes: value: - securitySchemeName: api_key type: apiKey apiKeyName: api_key in: header - securitySchemeName: http_secure type: http scheme: bearer bearerFormat: JWT - securitySchemeName: openIDConnectUrl type: openIDConnect openIdConnectUrl: https://example.com/openidconnectThe Server annotation represents a server used in an operation or used by all operations in an OpenAPI document.
server: url: https://exampleserver.com/v1/{myServerVariable}/{myServerVariable1} description: This is a description of the server variables: - name: myServerVariable defaultValue: 'Rachel' - name: myServerVariable1 defaultValue: 'Bob'The Servers annotation a container for multiple server definitions.
servers: - url: https://exampleserver.com/v1 description: This is a description of the server in version 1 - url: https://exampleserver.com/v2 description: This is a description of the server in version 2The ServerVariable annotation represents a server variable for server URL template substitution.
serverVariable: name: myServerVariable description: This describes the server variable enumeration: - Rachel - Tommy - Jana - Anna defaultValue: RachelThe Tag annotation represents a tag for the API endpoint.
tag: name: music description: Music operations externalDocs: url: www.url.com description: This is the descriptionThe Tags annotation creates a container of multiple tags.
tags: values: - name: MusicType - name: Artists $refs: "#/components/schemas/MusicType" "#/components/schemas/Artists"