add has swagger doc

Issue-ID: OPTFRA-283

Change-Id: I078f3a4d89c248c0d3c306431065e27ec5422350
Signed-off-by: Frank Sandoval <frank.sandoval@oamtechnologies.com>

1 files changed, 5 insertions, 465 deletions

diff --git a/docs/sections/offeredapis.rst b/docs/sections/offeredapis.rst
index 9ffb6fb..497f9a3 100644
--- a/docs/sections/offeredapis.rst
+++ b/docs/sections/offeredapis.rst
@@ -1,478 +1,18 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
 
 Offered APIs
 =============================================
 
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. Copyright (C) 2017-2018 AT&T Intellectual Property. All rights reserved.
-
-Homing API v1
-------------------
-
-*Updated: 28 Feb 2018*
-
 This document describes the Homing API, provided by the Homing and Allocation service (Conductor).
-It is a work in progress and subject to frequent revision.
-
-General API Information
--------------------------
-
-Authenticated calls that target a known URI but that use an HTTP method
-the implementation does not support return a 405 Method Not Allowed
-status. In addition, the HTTP OPTIONS method is supported for each known
-URI. In both cases, the Allow response header indicates the supported
-HTTP methods. See the API Errors section for more information about the
-error response structure.
-
-API versions
-------------------
-
-List all Homing API versions
-----------------------------
-
-**GET** ``/``\ F
-
-**Normal response codes:** 200
-
-.. code:: json
-
-    {
-      "versions": [
-        {
-          "status": "EXPERIMENTAL",
-          "id": "v1",
-          "updated": "2016-11-01T00:00:00Z",
-          "media-types": [
-            {
-              "base": "application/json",
-              "type": "application/vnd.onap.homing-v1+json"
-            }
-          ],
-          "links": [
-            {
-              "href": "http://has.ip/v1",
-              "rel": "self"
-            },
-            {
-              "href": "http://has.url/",
-              "type": "text/html",
-              "rel": "describedby"
-            }
-          ]
-        }
-      ]
-    }
-
-This operation does not accept a request body.
-
-Plans
------
-
-Create a plan
--------------
-
-**POST** ``/v1/plans``
-
--  **Normal response codes:** 201
--  **Error response codes:** badRequest (400), unauthorized (401),
-   internalServerError (500)
-
-Request an inventory plan for one or more related service demands.
-
-The request includes or references a declarative **template**,
-consisting of:
-
--  **Parameters** that can be referenced like macros
--  **Demands** for service made against inventory
--  **Locations** that are common to the overall plan
--  **Constraints** made against demands, resulting in a set of inventory
-   candidates
--  **Optimizations** to further narrow down the remaining candidates
 
-The response contains an inventory **plan**, consisting of one or more
-sets of recommended pairings of demands with an inventory candidate's
-attributes and region.
 
-Request Parameters
-~~~~~~~~~~~~~~~~~~
-
-+--------------------+-------+------------+-------------------+
-| Parameter          | Style | Type       | Description       |
-+====================+=======+============+===================+
-| ``name``           | plain | xsd:string | A name for the    |
-| (Optional)         |       |            | new plan. If a    |
-|                    |       |            | name is not       |
-|                    |       |            | provided, it      |
-|                    |       |            | will be           |
-|                    |       |            | auto-generated    |
-|                    |       |            | based on the      |
-|                    |       |            | homing            |
-|                    |       |            | template. This    |
-|                    |       |            | name must be      |
-|                    |       |            | unique within     |
-|                    |       |            | a given           |
-|                    |       |            | Conductor         |
-|                    |       |            | environment.      |
-|                    |       |            | When deleting     |
-|                    |       |            | a plan, its       |
-|                    |       |            | name will not     |
-|                    |       |            | become            |
-|                    |       |            | available for     |
-|                    |       |            | reuse until       |
-|                    |       |            | the deletion      |
-|                    |       |            | completes         |
-|                    |       |            | successfully.     |
-|                    |       |            | Must only         |
-|                    |       |            | contain           |
-|                    |       |            | letters,          |
-|                    |       |            | numbers,          |
-|                    |       |            | hypens, full      |
-|                    |       |            | stops,            |
-|                    |       |            | underscores,      |
-|                    |       |            | and tildes        |
-|                    |       |            | (RFC 3986,        |
-|                    |       |            | Section 2.3).     |
-|                    |       |            | This parameter    |
-|                    |       |            | is immutable.     |
-+--------------------+-------+------------+-------------------+
-| ``id``             | plain | csapi:UUID | The UUID of       |
-| (Optional)         |       |            | the plan. UUID    |
-|                    |       |            | is assigned by    |
-|                    |       |            | Conductor if      |
-|                    |       |            | no id is          |
-|                    |       |            | provided in       |
-|                    |       |            | the request.      |
-+--------------------+-------+------------+-------------------+
-| ``transaction_id`` | plain | csapi:UUID | The               |
-|                    |       |            | transaction id    |
-|                    |       |            | assigned by       |
-|                    |       |            | MSO. The logs     |
-|                    |       |            | should have       |
-|                    |       |            | this              |
-|                    |       |            | transaction id    |
-|                    |       |            | for tracking      |
-|                    |       |            | purposes.         |
-+--------------------+-------+------------+-------------------+
-| ``files``          | plain | xsd:dict   | Supplies the      |
-| (Optional)         |       |            | contents of       |
-|                    |       |            | files             |
-|                    |       |            | referenced in     |
-|                    |       |            | the template.     |
-|                    |       |            | Conductor         |
-|                    |       |            | templates can     |
-|                    |       |            | explicitly        |
-|                    |       |            | reference         |
-|                    |       |            | files by using    |
-|                    |       |            | the               |
-|                    |       |            | ``get_file``      |
-|                    |       |            | intrinsic         |
-|                    |       |            | function. The     |
-|                    |       |            | value is a        |
-|                    |       |            | JSON object,      |
-|                    |       |            | where each key    |
-|                    |       |            | is a relative     |
-|                    |       |            | or absolute       |
-|                    |       |            | URI which         |
-|                    |       |            | serves as the     |
-|                    |       |            | name of a         |
-|                    |       |            | file, and the     |
-|                    |       |            | associated        |
-|                    |       |            | value provides    |
-|                    |       |            | the contents      |
-|                    |       |            | of the file.      |
-|                    |       |            | Additionally,     |
-|                    |       |            | some template     |
-|                    |       |            | authors encode    |
-|                    |       |            | their user        |
-|                    |       |            | data in a         |
-|                    |       |            | local file.       |
-|                    |       |            | The Homing        |
-|                    |       |            | client (e.g.,     |
-|                    |       |            | a CLI) can        |
-|                    |       |            | examine the       |
-|                    |       |            | template for      |
-|                    |       |            | the               |
-|                    |       |            | ``get_file``      |
-|                    |       |            | intrinsic         |
-|                    |       |            | function          |
-|                    |       |            | (e.g.,            |
-|                    |       |            | ``{get_file: f    |
-|                    |       |            | ile.yaml}``)      |
-|                    |       |            | and add an        |
-|                    |       |            | entry to the      |
-|                    |       |            | ``files`` map     |
-|                    |       |            | with the path     |
-|                    |       |            | to the file as    |
-|                    |       |            | the name and      |
-|                    |       |            | the file          |
-|                    |       |            | contents as       |
-|                    |       |            | the value. Do     |
-|                    |       |            | not use this      |
-|                    |       |            | parameter to      |
-|                    |       |            | provide the       |
-|                    |       |            | content of the    |
-|                    |       |            | template          |
-|                    |       |            | located at the    |
-|                    |       |            | ``template_url``  |
-|                    |       |            | address.          |
-|                    |       |            | Instead, use      |
-|                    |       |            | the               |
-|                    |       |            | ``template``      |
-|                    |       |            | parameter to      |
-|                    |       |            | supply the        |
-|                    |       |            | template          |
-|                    |       |            | content as        |
-|                    |       |            | part of the       |
-|                    |       |            | request.          |
-+--------------------+-------+------------+-------------------+
-| ``template_url``   | plain | xsd:string | A URI to          |
-| (Optional)         |       |            | the location      |
-|                    |       |            | containing the    |
-|                    |       |            | template on       |
-|                    |       |            | which to          |
-|                    |       |            | perform the       |
-|                    |       |            | operation. See    |
-|                    |       |            | the               |
-|                    |       |            | description of    |
-|                    |       |            | the               |
-|                    |       |            | ``template``      |
-|                    |       |            | parameter for     |
-|                    |       |            | information       |
-|                    |       |            | about the         |
-|                    |       |            | expected          |
-|                    |       |            | template          |
-|                    |       |            | content           |
-|                    |       |            | located at the    |
-|                    |       |            | URI. This         |
-|                    |       |            | parameter is      |
-|                    |       |            | only required     |
-|                    |       |            | when you omit     |
-|                    |       |            | the               |
-|                    |       |            | ``template``      |
-|                    |       |            | parameter. If     |
-|                    |       |            | you specify       |
-|                    |       |            | both              |
-|                    |       |            | parameters,       |
-|                    |       |            | this parameter    |
-|                    |       |            | is ignored.       |
-+--------------------+-------+------------+-------------------+
-| ``template``       | plain | xsd:string | The template      |
-|                    |       | or xsd:dict| on which to       |
-|                    |       |            | perform the       |
-|                    |       |            | operation. See    |
-|                    |       |            | the Homing        |
-|                    |       |            | Template          |
-|                    |       |            | Guide             |
-|                    |       |            | for complete      |
-|                    |       |            | information on    |
-|                    |       |            | the format.       |
-|                    |       |            | This parameter    |
-|                    |       |            | is either         |
-|                    |       |            | provided as a     |
-|                    |       |            | ``string`` or     |
-|                    |       |            | ``dict`` in       |
-|                    |       |            | the JSON          |
-|                    |       |            | request body.     |
-|                    |       |            | For ``string``    |
-|                    |       |            | content it may    |
-|                    |       |            | be a JSON- or     |
-|                    |       |            | YAML-formatted    |
-|                    |       |            | Conductor         |
-|                    |       |            | template. For     |
-|                    |       |            | ``dict``          |
-|                    |       |            | content it        |
-|                    |       |            | must be a         |
-|                    |       |            | direct JSON       |
-|                    |       |            | representation    |
-|                    |       |            | of the            |
-|                    |       |            | Conductor         |
-|                    |       |            | template. This    |
-|                    |       |            | parameter is      |
-|                    |       |            | required only     |
-|                    |       |            | when you omit     |
-|                    |       |            | the               |
-|                    |       |            | ``template_url``  |
-|                    |       |            | parameter. If     |
-|                    |       |            | you specify       |
-|                    |       |            | both              |
-|                    |       |            | parameters,       |
-|                    |       |            | this value        |
-|                    |       |            | overrides the     |
-|                    |       |            | ``template_url``  |
-|                    |       |            | parameter         |
-|                    |       |            | value.            |
-+--------------------+-------+------------+-------------------+
-| ``timeout``        | plain | xsd:number | The timeout       |
-| (Optional)         |       |            | for plan          |
-|                    |       |            | creation in       |
-|                    |       |            | minutes.          |
-|                    |       |            | Default is 1.     |
-+--------------------+-------+------------+-------------------+
-| ``limit``          | plain | xsd:number | The maximum       |
-| (Optional)         |       |            | number of         |
-|                    |       |            | recommendations   |
-|                    |       |            | to return.        |
-|                    |       |            | Default is 1.     |
-+--------------------+-------+------------+-------------------+
-
-**NOTE**: ``files``, ``template_url``, and ``timeout`` are not yet
-supported.
+To view API documentation in the interactive swagger UI download the following and
+paste into the swagger tool here: https://editor.swagger.io
 
-Response Parameters
-~~~~~~~~~~~~~~~~~~~
+:download:`oof-has-api.json <./swaggerdoc/oof-has-api.json>`
 
-+--------------------+----------+------------+--------------------+
-| Parameter          | Style    | Type       | Description        |
-+====================+==========+============+====================+
-| ``plan``           | plain    | xsd:dict   | The ``plan``       |
-|                    |          |            | object.            |
-+--------------------+----------+------------+--------------------+
-| ``id``             | plain    | csapi:UUID | The UUID of        |
-|                    |          |            | the plan.          |
-+--------------------+----------+------------+--------------------+
-| ``transaction_id`` | plain    | csapi:UUID | The                |
-|                    |          |            | transaction id     |
-|                    |          |            | assigned by        |
-|                    |          |            | the MSO.           |
-+--------------------+----------+------------+--------------------+
-| ``name``           | plain    | xsd:string | The plan name.     |
-|                    |          |            |                    |
-+--------------------+----------+------------+--------------------+
-| ``status``         | plain    | xsd:string | The plan           |
-|                    |          |            | status. One of     |
-|                    |          |            | ``template``,      |
-|                    |          |            | ``translated``,    |
-|                    |          |            | ``solving``,       |
-|                    |          |            | ``solved``, or     | 
-|                    |          |            | ``error``. See     |
-|                    |          |            | **Plan             |
-|                    |          |            | Status** table     |
-|                    |          |            | for                |
-|                    |          |            | descriptions       |
-|                    |          |            | of each value.     |
-+--------------------+----------+------------+--------------------+
-| ``message``        | plain    | xsd:string | Additional         |
-|                    |          |            | context, if        |
-|                    |          |            | any, around        |
-|                    |          |            | the message        |
-|                    |          |            | status. If the     |
-|                    |          |            | status is          |
-|                    |          |            | ``error``,         |
-|                    |          |            | this may           |
-|                    |          |            | include a          |
-|                    |          |            | reason and         |
-|                    |          |            | suggested          |
-|                    |          |            | remediation,       |
-|                    |          |            | if available.      |
-+--------------------+----------+------------+--------------------+
-| ``links``          | plain    | xsd:list   | A list of URLs     |
-|                    |          |            | for the plan.      |
-|                    |          |            | Each URL is a      |
-|                    |          |            | JSON object        |
-|                    |          |            | with an            |
-|                    |          |            | ``href`` key       |
-|                    |          |            | indicating the     |
-|                    |          |            | URL and a          |
-|                    |          |            | ``rel`` key        |
-|                    |          |            | indicating its     |
-|                    |          |            | relationship       |
-|                    |          |            | to the plan in     |
-|                    |          |            | question.          |
-|                    |          |            | There may be       |
-|                    |          |            | multiple links     |
-|                    |          |            | returned. The      |
-|                    |          |            | ``self``           |
-|                    |          |            | relationship       |
-|                    |          |            | identifies the     |
-|                    |          |            | URL of the         |
-|                    |          |            | plan itself.       |
-+--------------------+----------+------------+--------------------+
-| ``recommendations``| plain    | xsd:list   | A list of one      |
-|                    |          |            | or more            |
-|                    |          |            | recommendationS.   |
-|                    |          |            | A                  |
-|                    |          |            | recommendation     |
-|                    |          |            | pairs each         |
-|                    |          |            | requested          |
-|                    |          |            | demand with an     |
-|                    |          |            | inventory          |
-|                    |          |            | provider, a        |
-|                    |          |            | single             |
-|                    |          |            | candidate, and     |
-|                    |          |            | an opaque          |
-|                    |          |            | dictionary of      |
-|                    |          |            | attributes.        |
-|                    |          |            | Refer to the       |
-|                    |          |            | Demand             |
-|                    |          |            | candidate          |
-|                    |          |            | schema in the      |
-|                    |          |            | Homing             |
-|                    |          |            | Template           |
-|                    |          |            | Guide              |
-|                    |          |            | for further        |
-|                    |          |            | details. (Note     |
-|                    |          |            | that, when         |
-|                    |          |            | ``inventory_type`` |
-|                    |          |            | is ``cloud``       |
-|                    |          |            | the                |
-|                    |          |            | candidate's        |
-|                    |          |            | ``candidate_id``   |
-|                    |          |            | field is           |
-|                    |          |            | redundant and      |
-|                    |          |            | thus omitted.)     |
-+--------------------+----------+------------+--------------------+  
-
-Plan Status
-~~~~~~~~~~~
-
-+----------------+-----------------+
-| Status         | Description     |
-+================+=================+
-| ``template``   | Plan request    |
-|                | and homing      |
-|                | template have   |
-|                | been received.  |
-|                | Awaiting        |
-|                | translation.    |
-+----------------+-----------------+
-| ``translated`` | Homing          |
-|                | template has    |
-|                | been            |
-|                | translated,     |
-|                | and candidates  |
-|                | have been       |
-|                | obtained from   |
-|                | inventory       |
-|                | providers.      |
-|                | Awaiting        |
-|                | solving.        |
-+----------------+-----------------+
-| ``solving``    | Search for a    |
-|                | solution is in  |
-|                | progress. This  |
-|                | may             |
-|                | incorporate     |
-|                | requests to     |
-|                | service         |
-|                | controllers     |
-|                | for additional  |
-|                | information.    |
-+----------------+-----------------+
-| ``solved``     | Search is       |
-|                | complete. A     |
-|                | solution with   |
-|                | one or more     |
-|                | recommendations |
-|                | was found.      |
-+----------------+-----------------+
-| ``not found``  | Search is       |
-|                | complete. No    |
-|                | recommendations |
-|                | were found.     |
-+----------------+-----------------+
-| ``error``      | An error was    |
-|                | encountered.    |
-+----------------+-----------------+
+.. swaggerv2doc:: ./swaggerdoc/oof-has-api.json
 
 State Diagram
 ^^^^^^^^^^^^^