Skip to content

Static File Samples

Jump to bottom
Arthur De Magalhaes edited this page Jun 1, 2018 · 2 revisions

MP OpenAPI 1.0 Static File Samples

Callback Sample

The Callback annotation represents a callback URL that will be invoked.

callback:
  name: myCallback
    callBackUrlExpression: www.myurl.com
    callbackOperation:
      method: POST

Callbacks Sample

The Callbacks annotation represents an array of Callback URLs that can be invoked.

callbacks:
  value:
    name: myCallback
    callBackUrlExpression: www.myurl.com
    callbackOperation:
      method: POST

CallbackOperation Sample

The 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: extensionVal

Components Sample

The 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: myCallback

Extension Sample

The Extension annotation adds an extension with contained properties.

extension:
  name: xHeader
  value: extensionValx

Extensions Sample

The Extensions annotation adds custom properties to an extension.

extensions:
  - name: xHeader
    value: extensionValx
  - name: yHeader
    value: extensionValy

ExternalDocumentation Sample

The ExternalDocumentation annotation references an external resource for extended documentation.

externalDocumentation:
  description: A short description of the target documentation
  url: www.urlfortargetdocumentation.com

Header Sample

The Header annotation describes a single header object.

header:
  name: headerName
  description: the header's description
  schema:
    name: schemaName
  required: true
  deprecated: false
  allowEmptyValue: true

Contact Sample

The Contact annotation describes the contact information for the exposed API.

contact:
  name: contactName
  url: www.urlofcontact.com
  email: [email protected]

Info Sample

The 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: [email protected]
  license:
    name: licenseName
  version: '2.0.1'

License Sample

The License annotation describes the license information for the exposed API.

license:
  name: licenseName
  url: www.myurlformylicense.com

Link Sample

The 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: RACH

LinkParameter Sample

The LinkParameter annotation represents a parameter to pass to the linked operation.

linkParameter:
  name: linkParameterName
  expression: the parameter's literal value or expression

Content Sample

The 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: encodingName

DiscriminatorMapping Sample

The 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: schemaName

Encoding Sample

The 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: headerName

ExampleObject Sample

The 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 example

Schema Sample

The 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: false

OpenAPIDefinition Sample

The OpenAPIDefinition annotation provides general metadata for an OpenAPI definition.

openAPIDefinition:
  info:
    title: Music Title
    contact:
      name: Mr.X
      email: [email protected]
    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: Music

Operation Sample

The 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: true

Parameter Sample

The 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: Baby

Parameters Sample

The Parameters annotation encapsulates input parameters.

parameters:
  value:
    - name: musicAlbums
    - name: artists

RequestBody Sample

The 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 instance

APIResponse Sample

The 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'

APIResponses Sample

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 response

OAuthFlow Sample

The 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 reviews

OAuthFlows Sample

The 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 reviews

OAuthScope Sample

The OAuthScope annotation represents an OAuth scope.

OAuthScope:
  name: read:reviews
  description: read some reviews

SecurityRequirement Sample

The SecurityRequirement annotation specifies a security requirement for an operation.

securityRequirement:
  name: oauth2
  scopes: read:reviews

SecurityRequirements Sample

The 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:reviews

SecurityRequirementsSet Sample

The SecurityRequirementsSet annotation represents an array of security requirements that need to be satisfied.

securityRequirementSet:
  - name: api_key
    scopes: read:reviews
  - name: oauth2
    scopes: read:reviews

SecurityScheme Sample

The 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 reviews

SecuritySchemes Sample

The 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/openidconnect

Server Sample

The 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'

Servers Sample

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 2

ServerVariable Sample

The 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: Rachel

Tag Sample

The Tag annotation represents a tag for the API endpoint.

tag:
  name: music
  description: Music operations
  externalDocs:
    url: www.url.com
    description: This is the description

Tags Sample

The Tags annotation creates a container of multiple tags.

tags:
  values:
    - name: MusicType
    - name: Artists
  $refs:
    "#/components/schemas/MusicType"
    "#/components/schemas/Artists"
Clone this wiki locally