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

swagger: '2.0'
info:
  version: '3.0.0'
  title: '[Demo] Orders API'
  contact: 
    name: Z
    email: "z@goodapi.co"
  description: |
    Sample API conforming to [adidas API Guidelines](https://adidas.gitbook.io/api-guidelines/).

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

schemes:
  - https

host: "example.com"

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:
            allOf:
              - $ref: '#/definitions/supermodelIoAdidasApiHAL'
            example:
              _links:
                self:
                  href: /
                orders:
                  href: /orders

  /orders:
    x-summary: List of Orders

    get:
      summary: Retrieve List of Orders
      description: Retrieves a list of orders with pagination.
      parameters:
        - $ref: '#/parameters/offset'
        - $ref: '#/parameters/limit'
      responses:
        200:
          description: The list of Orders
          schema:
            $ref: '#/definitions/supermodelIoAdidasExamplesOrderApiOrders'

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

  /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
      description: Retrieves an order with specified fields.
      parameters:
        - $ref: '#/parameters/fields'
      responses:
        200:
          description: A particular Order
          schema:
            $ref: '#/definitions/supermodelIoAdidasExamplesOrderApiOrder'
        404:
          description: The request Order wasn't found
          headers:
            Content-Type:
              type: string
              default: application/problem+json
          schema:
            allOf:
              - $ref: '#/definitions/supermodelIoAdidasApiProblemDetail'
            example:
              title: 'Not Found'
              detail: 'Cannot find the requested order'
              status: 404
              instance: '/orders/1234'

    patch:
      summary: Update Order
      description: Does a partial update of an order.
      consumes:
        - application/json
      parameters:
        - name: Order
          in: body
          description: Partial order update
          required: true
          schema:
            $ref: '#/definitions/supermodelIoAdidasExamplesOrderApiOrderPatch'
      responses:
        200:
          description: The Order was updated
          schema:
            $ref: '#/definitions/supermodelIoAdidasExamplesOrderApiOrder'

    delete:
      summary: Delete Order
      description: Deletes an order without returning its instance.
      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

# DO NOT EDIT
# This definitions section is automatically generated by supermodel.io
#
# http://supermodel.io
# https://github.com/supermodel/supermodel-cli
definitions:
  supermodelIoAdidasExamplesOrderApiOrder:
    title: Order HAL Representation
    type: object
    allOf:
      - $ref: '#/definitions/supermodelIoAdidasApiHAL'
      - $ref: '#/definitions/supermodelIoAdidasExamplesOrderOrder'
    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
  supermodelIoAdidasExamplesOrderApiOrderPatch:
    title: OrderPatch
    description: OrderPatch model description
    type: object
    allOf:
      - $ref: '#/definitions/supermodelIoAdidasExamplesOrderOrder'
    example:
      status: cancelled
      orderNumber: 1
      itemCount: 2
  supermodelIoAdidasExamplesOrderApiOrders:
    title: Collection of Orders HAL Representation
    type: object
    allOf:
      - $ref: '#/definitions/supermodelIoAdidasApiHAL'
    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:
          - _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
  supermodelIoAdidasExamplesOrderApiProblemDetail:
    title: Problem Detail
    type: object
    allOf:
      - $ref: '#/definitions/supermodelIoAdidasApiProblemDetail'
  supermodelIoAdidasApiHAL:
    title: HAL
    description: >-
      JSON Hypertext Application Language. Definition of [HAL message
      format](https://tools.ietf.org/html/draft-kelly-json-hal-08)
    type: object
    properties:
      _links:
        type: object
        additionalProperties:
          allOf:
            - $ref: '#/definitions/supermodelIoAdidasApiHALDefinitionsHalLinkObject'
            - type: array
              items:
                $ref: '#/definitions/supermodelIoAdidasApiHALDefinitionsHalLinkObject'
        properties:
          curies:
            allOf:
              - $ref: '#/definitions/supermodelIoAdidasApiHALDefinitionsHalCuriesLink'
              - type: array
                items:
                  $ref: >-
                    #/definitions/supermodelIoAdidasApiHALDefinitionsHalCuriesLink
      _embedded:
        type: object
        additionalProperties:
          allOf:
            - $ref: '#/definitions/supermodelIoAdidasApiHAL'
            - type: array
              items:
                $ref: '#/definitions/supermodelIoAdidasApiHAL'
  supermodelIoAdidasApiHALDefinitionsHalLinkObject:
    title: HAL Link Object
    type: object
    properties:
      href:
        type: string
      templated:
        type: boolean
      type:
        type: string
      deprecation:
        type: string
      name:
        type: string
      profile:
        type: string
      title:
        type: string
      hreflang:
        type: string
    required:
      - href
  supermodelIoAdidasApiHALDefinitionsHalCuriesLink:
    title: HAL Curies Link
    allOf:
      - type: object
        properties:
          templated:
            enum:
              - true
        required:
          - templated
      - $ref: '#/definitions/supermodelIoAdidasApiHALDefinitionsHalLinkObject'
  supermodelIoAdidasExamplesOrderOrder:
    title: Order
    type: object
    description: Order model description
    properties:
      orderNumber:
        type: number
      itemCount:
        type: number
      status:
        type: string
    required:
      - orderNumber
      - itemCount
    example:
      orderNumber: 42
      itemCount: 3
      status: pending
  supermodelIoAdidasApiProblemDetail:
    title: Problem Details for HTTP APIs
    description: >-
      Definition of [RFC7807](https://tools.ietf.org/html/rfc7807) problem
      detail
    type: object
    properties:
      type:
        type: string
      title:
        type: string
      status:
        type: number
      detail:
        type: string
      instance:
        type: string
    required:
      - title
      - detail