Add swagger REST API documentation

docs/swagger-schema.yaml

+swagger: "2.0"
+info:
+  description: "Capability service for the SSA Workspaces project"
+  version: "1.0.0"
+  title: "Capability Service"
+  contact:
+    email: "dms-ssa@nrao.edu"
+host: "shipman.aoc.nrao.edu"
+tags:
+  - name: "capabilities"
+    description: "Access capabilities and create requests"
+  - name: "requests"
+    description: "Access to and submit capability requests"
+schemes:
+  - "http"
+paths:
+  /capability/{name}:
+    get:
+      tags:
+        - "capabilities"
+      summary: "View the named capability"
+      description: ""
+      operationId: "view_capability"
+      consumes:
+        - "application/json"
+      produces:
+        - "application/json"
+      parameters:
+        - name: "name"
+          in: "path"
+          description: "name of capability to view"
+          required: true
+          type: "string"
+      responses:
+        "400":
+          description: "Invalid name supplied"
+        "404":
+          description: "Capability not found"
+        "200":
+          description: "successful operation"
+          schema:
+            $ref: "#/definitions/Capability"
+    post:
+      tags:
+        - "capabilities"
+      summary: "Update an existing capability"
+      description: ""
+      operationId: "edit_capability"
+      consumes:
+        - "application/json"
+      produces:
+        - "application/json"
+      parameters:
+        - name: "name"
+          in: "path"
+          description: "name of capability to update"
+          required: true
+          type: "string"
+        - in: "body"
+          name: "body"
+          description: "Capability object that needs to be added to the system"
+          required: true
+          schema:
+            $ref: "#/definitions/Capability"
+      responses:
+        "400":
+          description: "Invalid name supplied"
+        "404":
+          description: "Capability not found"
+        "200":
+          description: "successful operation"
+          schema:
+            $ref: "#/definitions/Capability"
+  /capability/{name}/enable:
+    post:
+      tags:
+        - "capabilities"
+      summary: "Enable a capability"
+      operationId: "enable_capability"
+      consumes:
+        - "application/json"
+      produces:
+        - "application/json"
+      parameters:
+        - name: "name"
+          in: "path"
+          description: "name of capability to enable"
+          required: true
+          type: "string"
+      responses:
+        "400":
+          description: "Invalid name supplied"
+        "404":
+          description: "Capability not found"
+  /capability/{name}/disable:
+    post:
+      tags:
+        - "capabilities"
+      summary: "Disable a capability"
+      operationId: "disable_capability"
+      consumes:
+        - "application/json"
+      produces:
+        - "application/json"
+      parameters:
+        - name: "name"
+          in: "path"
+          description: "name of capability to disable"
+          required: true
+          type: "string"
+      responses:
+        "400":
+          description: "Invalid name supplied"
+        "404":
+          description: "Capability not found"
+  /capability/{name}/requests/{id}:
+    get:
+      tags:
+        - "requests"
+      summary: "View the identified capability request"
+      description: ""
+      operationId: "view_capability_request"
+      consumes:
+        - "application/json"
+      produces:
+        - "application/json"
+      parameters:
+        - name: "name"
+          in: "path"
+          description: "name of capability this request belongs to"
+          required: true
+          type: "string"
+        - name: "id"
+          in: "path"
+          description: "ID of capability request"
+          required: true
+          type: "integer"
+          format: "int64"
+      responses:
+        "400":
+          description: "Invalid capability name or request ID supplied"
+        "404":
+          description: "Capability request not found"
+        "200":
+          description: "successful operation"
+          schema:
+            $ref: "#/definitions/CapabilityRequest"
+    post:
+      tags:
+        - "requests"
+      summary: "Update an existing capability request"
+      description: ""
+      operationId: "edit_capability_request"
+      consumes:
+        - "application/json"
+      produces:
+        - "application/json"
+      parameters:
+        - name: "name"
+          in: "path"
+          description: "name of capability this request belongs to"
+          required: true
+          type: "string"
+        - name: "id"
+          in: "path"
+          description: "ID of capability request"
+          required: true
+          type: "integer"
+          format: "int64"
+        - in: "body"
+          name: "body"
+          description: "Capability object that needs to be added to the system"
+          required: true
+          schema:
+            $ref: "#/definitions/Capability"
+      responses:
+        "400":
+          description: "Invalid name supplied"
+        "404":
+          description: "Capability not found"
+    delete:
+      tags:
+        - "requests"
+      summary: "Delete a capability request"
+      description: ""
+      operationId: "delete_capability_request"
+      consumes:
+        - "application/json"
+      produces:
+        - "application/json"
+      parameters:
+        - name: "name"
+          in: "path"
+          description: "name of capability this request belongs to"
+          required: true
+          type: "string"
+        - name: "id"
+          in: "path"
+          description: "ID of capability request"
+          required: true
+          type: "integer"
+          format: "int64"
+      responses:
+        "400":
+          description: "Invalid name supplied"
+        "403":
+          description: "Permission denied; capability request already executed"
+        "404":
+          description: "Capability not found"
+  /capability/{name}/requests/{id}/submit:
+    post:
+      tags:
+        - "requests"
+      summary: "Submit a capability request for execution"
+      description: ""
+      operationId: "submit_capability_request"
+      consumes:
+        - "application/json"
+      produces:
+        - "application/json"
+      parameters:
+        - name: "name"
+          in: "path"
+          description: "name of capability this request belongs to"
+          required: true
+          type: "string"
+        - name: "id"
+          in: "path"
+          description: "ID of capability request"
+          required: true
+          type: "integer"
+          format: "int64"
+      responses:
+        "400":
+          description: "Invalid name supplied"
+        "404":
+          description: "Capability not found"
+
+definitions:
+  Capability:
+    type: "object"
+    properties:
+      name:
+        type: "string"
+      steps:
+        type: "string"
+      max_jobs:
+        type: "integer"
+        format: "int64"
+  CapabilityRequest:
+    type: "object"
+    properties:
+      body:
+        type: "object"
+externalDocs:
+  description: "More about the capability service"
+  url: "http://builder.aoc.nrao.edu/ssa/architecture/workspaces"
\ No newline at end of file