add example, use supermodel models as source of truth for hal and problem detail

examples/demo-orderapi.oas2.yaml

@@ -0,0 +1,384 @@
+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'

spectral.yml

@@ -72,7 +72,7 @@ rules:
       function: schema
       functionOptions:
         schema:
-          $ref: ./hal.yaml
+          $ref: ./supermodel/adidas/api/HAL.yaml
   response-error-problem: # schemes and/or produces
     description: All error responses MUST be of media type `application/problem+json`
     severity: error
@@ -86,7 +86,7 @@ rules:
       function: schema
       functionOptions:
         schema:
-          $ref: ./problem.yaml
+          $ref: ./supermodel/adidas/api/ProblemDetail.yaml
   request-support-json: # This will have to take into account the schemes as well as consumes parameter
     description: Every request SHOULD support `application/json` media type
     severity: warn

supermodel/.super

@@ -0,0 +1,3 @@
+{
+  "host": "https://supermodel.io"
+}

supermodel/adidas/api/HAL.yaml

@@ -1,14 +1,9 @@
-# $id: http://supermodel.io/andrzej/hAL
+$id: http://supermodel.io/adidas/api/HAL
-# $schema: http://json-schema.org/draft-04/schema#
+$schema: http://json-schema.org/draft-07/schema#
-
 title: HAL
 description: JSON Hypertext Application Language. Definition of [HAL message format](https://tools.ietf.org/html/draft-kelly-json-hal-08)
 type: object
-# required:
-#   - errorCauser
 properties:
-  # errorCauser:
-  #   type: string
   _links:
     type: object
     additionalProperties:

supermodel/adidas/api/ProblemDetail.yaml

@@ -1,5 +1,5 @@
-# $id: http://supermodel.io/adidas/api/ProblemDetail
+$id: http://supermodel.io/adidas/api/ProblemDetail
-# $schema: http://json-schema.org/draft-07/schema#
+$schema: http://json-schema.org/draft-07/schema#
 title: Problem Details for HTTP APIs
 description: Definition of [RFC7807](https://tools.ietf.org/html/rfc7807) problem detail
 type: object