From fa0c3ce07e66335369ecc0808351d5e1cab6e56a Mon Sep 17 00:00:00 2001
From: Jan Kaluza <jkaluza@redhat.com>
Date: Nov 23 2018 11:47:22 +0000
Subject: When 'flasgger' is available, server ODCS API on /apidocs endpoint.


---

diff --git a/server/odcs/server/views.py b/server/odcs/server/views.py
index 92256b4..53fa445 100644
--- a/server/odcs/server/views.py
+++ b/server/odcs/server/views.py
@@ -40,6 +40,32 @@ from odcs.server.auth import requires_role, login_required
 from odcs.server.auth import require_scopes
 
 
+try:
+    from flasgger import Swagger
+    template = {
+        "swagger": "2.0",
+        "info": {
+            "title": "ODCS API",
+            "description": "API for On Demand Compose Service",
+            "version": str(version)
+        },
+        "schemes": [
+            "https"
+        ],
+    }
+
+    app.config['SWAGGER'] = {
+        'title': 'ODCS API',
+        'uiversion': 3
+    }
+
+    swagger = Swagger(app, template=template)
+except ImportError:
+    log.warning(
+        "The 'flasgger' module is not installed. "
+        "The /apidocs endpoint is disabled.")
+
+
 api_v1 = {
     'composes': {
         'url': '/api/1/composes/',
@@ -105,6 +131,72 @@ class ODCSAPI(MethodView):
             return conf.seconds_to_live
 
     def get(self, id):
+        """
+        Returns the ODCS Compose(s).
+        ---
+        security:
+          - negotiationAuth: []
+        securitySchemes:
+          negotiationAuth:
+            type: http
+            scheme: negotiate
+            in: header
+        parameters:
+        - name: id
+          in: path
+          description: ID of ODCS compose to return.
+          type: integer
+          required: false
+        - name: owner
+          in: query
+          description: Owner of a compose to return.
+          type: string
+          required: false
+        - name: source_type
+          in: query
+          description: ID of Compose source type to return.
+          type: integer
+          required: false
+        - name: source
+          in: query
+          description: Name of the source of compose to return.
+          type: string
+          required: false
+        - name: state
+          in: query
+          description: ID of Compose state.
+          type: integer
+          required: false
+        - name: order_by
+          in: query
+          description: Defines the ordering of returned composes. The "-"
+                       prefix defines descending order.
+          type: string
+          required: false
+          default: -id
+          enum: ["id", "owner", "source_Type", "koji_event",
+                 "state", "time_to_expire", "time_submitted",
+                 "time_done", "time_removed",
+                 "-id", "-owner", "-source_Type", "-koji_event",
+                 "-state", "-time_to_expire", "-time_submitted",
+                 "-time_done", "-time_removed"]
+        - name: page
+          in: query
+          description: Index of page with composes to return.
+          type: integer
+          required: false
+        - name: per_page
+          in: query
+          description: Number of returned composes per page.
+          type: integer
+          required: false
+          default: 10
+        responses:
+          200:
+            description: List of ODCS composes.
+          401:
+            description: Unauthorized.
+        """
         if id is None:
             p_query = filter_composes(request)
 
@@ -187,6 +279,58 @@ class ODCSAPI(MethodView):
     @require_scopes('new-compose')
     @requires_role('allowed_clients')
     def post(self):
+        """
+        Submits new compose request.
+        ---
+        parameters:
+        - name: request
+          in: body
+          description: Compose request in JSON format.
+          schema:
+            $ref: '#/definitions/ComposeRequest'
+          required: true
+        definitions:
+          ComposeRequest:
+            type: object
+            properties:
+              source:
+                $ref: '#/definitions/ComposeSource'
+              flags:
+                type: array
+                items:
+                  type: string
+                  enum: ["no_deps", "no_inheritance"]
+              arches:
+                type: array
+                items:
+                  type: string
+          ComposeSource:
+            type: object
+            properties:
+              source:
+                type: string
+              type:
+                type: string
+                enum: ["tag", "module", "build"]
+                required: true
+              packages:
+                type: array
+                items:
+                  type: string
+              builds:
+                type: array
+                items:
+                  type: string
+              sigkeys:
+                type: array
+                items:
+                  type: string
+        responses:
+          200:
+            description: Submitted ODCS compose request.
+          401:
+            description: Unauthorized.
+        """
         data = request.get_json(force=True)
         if not data:
             raise ValueError('No JSON POST data submitted')