Responses External file OpenAPI 3.0 speccy example

main.yml

openapi: "3.0.1"
info:
  description: "Something to demo that Link components are not linting"
  version: "1.0.0"
  title: "Test API"
  contact:
    name: "Chris Lock"
    url: "https://catharsis.co.uk"
servers:
  - url: "https://api.not-a-real-api.com"
tags:
  - name: "administrators"
    description: "Administrator end points"
paths:
  /administrators/{userId}:
    parameters:
      - $ref: "#/components/parameters/userId"
    put:
      operationId: "assignAdministrator"
      tags:
        - "users"
        - "administrators"
      summary: "Assign an Administrator to a User"
      requestBody:
        $ref: "#/components/requestBodies/administratorRequest"
      responses:
        200:
          $ref: "responses.yml#/administratorResponse"
        404:
          $ref: "responses.yml#/404"
        405:
          $ref: "responses.yml#/405"
        410:
          $ref: "responses.yml#/410"

components:
  securitySchemes:
    oauth_auth:
      type: "oauth2"
      flows:
        clientCredentials:
          tokenUrl: "/oauth/token"
          scopes:
            "read:user": "read a users"
            "write:user": "write the users"
        password:
          tokenUrl: "/oauth/token"
          refreshUrl: "/oauth/token"
          scopes:
            "read:user": "read a users"
            "write:user": "write the users"

  parameters:
    userId:
      description: "The id of the User"
      in: "path"
      name: "userId"
      required: true
      schema:
        type: "integer"

  requestBodies:
    administratorRequest:
      content:
        application/json:
          schema:
            $ref: "schemas.yml#/Administrator"

  # Left in as reference  
  # responses:
  #   204:
  #     description: "No content"
  #   404:
  #     description: "Resource not found"
  #   405:
  #     description: "Invalid input"
  #   410:
  #     description: "Resource has been deleted"
  #   administratorResponse:
  #     description: "The Administrator object response"
  #     content:
  #       application/json:
  #         schema:
  #           $ref: "schemas.yml#/Administrator"
  #     links:
  #       getUserById:
  #         operationId: "getUser"
  #         parameters:
  #           userId: "$request.path.userId"

security:
  - oauth_auth: []

package.json

{
  "dependencies": {
    "node": "8",
    "speccy": "^0.5.0"
  }
}

responses.yml

204:
  description: "No content"
404:
  description: "Resource not found"
405:
  description: "Invalid input"
410:
  description: "Resource has been deleted"
administratorResponse:
  description: "The Administrator object response"
  content:
    application/json:
      schema:
        $ref: "schemas.yml#/Administrator"
  links:
    getUserById:
      operationId: "getUser"
      parameters:
        userId: "$request.path.userId"

schemas.yml

Administrator:
  type: "object"
  properties:
    id:
      type: "integer"
      format: "int64"
      readOnly: true
    name:
      type: "string"
    mail:
      type: "string"
      format: "email"
    enabled:
      type: "boolean"