api-guidelines/examples/demo-orderapi.oas2.yaml

swagger: '2.0'
info:
  version: '2.0.0'
  title: '[Demo] Orders API'
  description: |
    Sample API conforming to [adidas API Guidelines](https://adidas.gitbook.io/api-guidelines/).
    
    This API is [documented at Apiary](http://docs.demotemplate.apiary.io)
    and stored on GitHub.

produces:
  - application/hal+json      # Representation message format
  - application/problem+json  # Error message format

schemes:
  - https

securityDefinitions:
   "API Key":
     type: apiKey
     in: header
     name: x-api-key

security:
  - "API Key": []

paths:
  /:
    x-summary: API Root

    get:
      summary: Retrieve API Root
      description: The API Root contains the initial set of link relations.
      responses:
        200:
          description: The root of the API
          schema:
            $ref: '#/definitions/halRoot'

  /orders:
    x-summary: List of Orders

    get:
      summary: Retrieve List of Orders
      parameters:
        - $ref: '#/parameters/offset'
        - $ref: '#/parameters/limit'
      responses:
        200:
          description: The list of Orders
          schema:
            $ref: '#/definitions/halOrders'

    post:
      summary: Create a New Order
      consumes:
        - application/json
      parameters:
        - name: Order
          in: body
          description: Order to be created
          required: true
          schema:
            $ref: '#/definitions/order'
      responses:
        201:
          description: Newly created order
          schema:
            $ref: '#/definitions/halOrder'

  /orders/{orderId}:
    x-summary: Order

    parameters:
      - name: orderId
        in: path
        description: Id of the Order
        required: true
        type: string
        x-example: '1234'

    get:
      summary: Retrieve Order
      parameters:
        - $ref: '#/parameters/fields'
      responses:
        200:
          description: A particular Order
          schema:
            $ref: '#/definitions/halOrder'
        404:
          description: The request Order wasn't found
          headers:
            Content-Type:
              type: string
              default: application/problem+json
          schema:
            $ref: '#/definitions/orderNotFound'

    patch:
      summary: Update Order
      consumes:
        - application/json
      parameters:
        - name: Order
          in: body
          description: Partial order update
          required: true
          schema:
            $ref: '#/definitions/orderPatch'
      responses:
        200:
          description: The Order was updated
          schema:
            $ref: '#/definitions/halOrder'

    delete:
      summary: Delete Order
      produces: []
      responses:
        204:
          description: The Order was deleted

parameters:
  # adidas API guidelines: Pagination
  offset:
    name: offset
    in: query
    description: Number of results to skip from the start of the list
    required: false
    type: string
    default: '0'
    x-example: '10'

  # adidas API guidelines: Pagination
  limit:
    name: limit
    in: query
    description: The maximum number of reusults to return
    required: false
    type: string
    default: '10'
    x-example: '5'

  # adidas API guidelines: Sparse fieldset
  fields:
    name: fields
    in: query
    description: Comma-separated list of fields to include in the response
    required: false
    type: array
    items:
      type: string
    collectionFormat: csv
    x-example:
      - articleNumber
      - modelNumber

  # adidas API guidelines: Sparse fieldset
  embedded:
    name: embedded
    in: query
    description: Comma-separated list of resource (relations) to embed in the response
    required: false
    type: array
    items:
      type: string
    collectionFormat: csv
    x-example:
      - prices
      - assets

definitions:
  #
  # API Root
  #
  halRoot:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
    example:
      _links:
        self:
          href: /
        orders:
          href: /orders

  #
  # Orders Resource
  #
  halOrders:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
    example:
      _links:
        self:
          href: /orders

        create:
          href: /orders

        next:
          href: /orders?offset=5&limit=5

        first:
          href: /orders?offset=0&limit=5

        last:
          href: /orders?offset=40&limit=5

      _embedded:
        order:
          - $ref: '#/definitions/halOrder/example'

  #
  # Order Resource
  #

  # HAL Wrapper
  halOrder:
    type: object
    allOf:
      - $ref: '#/definitions/halResource'
      - $ref: '#/definitions/order'
    example:
      _links:
        self:
          href: /orders/1234

        edit:
          href: /orders/1234

        delete:
          href: /orders/1234

        profile:
          href: https://adidas-group.com/gdm/OMS

      orderNumber: 1234
      itemCount: 42
      status: pending

  # Partial Order
  orderPatch:
    type: object
    allOf:
      - $ref: '#/definitions/order'
    example:
      status: cancelled
      orderNumber: 1
      itemCount: 2

  # Order
  order:
    type: object
    properties:
      orderNumber:
        type: number
      itemCount:
        type: number
      status:
        type: string
    required:
      - orderNumber
      - itemCount
    example:
      orderNumber: 42
      itemCount: 3
      status: pending

  # Order Not Found Error
  orderNotFound:
    type: object
    allOf:
      - $ref: '#/definitions/problemDetail'
    example:
      title: 'Not Found'
      detail: 'Cannot find the requested order'
      status: 404
      instance: '/orders/1234'

  #
  # -- DO NOT EDIT BEYOND THIS POINT --
  #

  # Media Types Definitions

  #
  # application/problem+json
  #
  problemDetail:
    type: object
    properties:
      type:
        type: string
      title:
        type: string
      status:
        type: number
      detail:
        type: string
      instance:
        type: string
    required:
      - title
      - detail

  #
  # application/hal+json defintion
  #
  halLinkObject:
    type: object
    required:
      - href
    properties:
      href:
        type: string
      templated:
        type: boolean
      #
      # WARN: Some version of OAS parser can have problem with property being called "type"
      # resulting in the error 'Schema "type" key must be a string'.
      #
      # For this reason we have commented out the "type" property of the link object.
      # See https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5.3 for the definiton of
      # HAL's link object type property.
      #
      # type:
      #  type: string
      deprecation:
        type: string
      name:
        type: string
      profile:
        type: string
      title:
        type: string
      hreflang:
        type: string

  halCuriesLink:
    title: HAL Curies Link
    allOf:
      - type: object
        properties:
          templated:
            enum:
              - true
        required:
          - templated
      - $ref: '#/definitions/halLinkObject'

  halResource:
    title: HAL Resource Object
    type: object
    properties:
      _links:
        type: object
        additionalProperties:
          # WARN: Should be "anyOf" but "anyOf" isn't supported in Swagger 2.0
          allOf:
            - $ref: '#/definitions/halLinkObject'
            - type: array
              items:
                - $ref: '#/definitions/halLinkObject'
        properties:
          curies:
            # WARN: Should be "anyOf" but "anyOf" isn't supported in Swagger 2.0
            allOf:
              - $ref: '#/definitions/halCuriesLink'
              - type: array
                items:
                  - $ref: '#/definitions/halCuriesLink'
      _embedded:
        type: object
        additionalProperties: true
        # WARN: Apiary doesn't support circular references
        # additionalProperties:
        #   anyOf:
        #     - $ref: '#/definitions/hal_resource'
        #     - type: array
        #       items:
        #         - $ref: '#/definitions/hal_resource'