Jump to: navigation, search

Difference between revisions of "StarlingX/Designer REST API Documentation"

 
(11 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
== API Documentation Guideline ==
+
 
 +
 
 +
See the [https://docs.starlingx.io/contributor/api_contribute_guide.html StarlingX API Contributor Guide] for information on contributing to StarlingX API documentation.
 +
This wiki page has been deprecated.
 +
 
 +
<!-- == Locations ==
  
 
OpenStack API working group has defined a guideline to follow for API documentation when a project provides a REST API service. API documentation information comes from RST source files stored in the project repository, that when built, generate HTML files. More details about the OpenStack API documentation can be found at:
 
OpenStack API working group has defined a guideline to follow for API documentation when a project provides a REST API service. API documentation information comes from RST source files stored in the project repository, that when built, generate HTML files. More details about the OpenStack API documentation can be found at:
Line 5: Line 10:
  
 
StarlingX API Reference documentation exists in the following projects:
 
StarlingX API Reference documentation exists in the following projects:
−
* stx-config: StarlingX System Configuration Management
+
* '''stx-config:''' StarlingX System Configuration Management
−
* stx-docs: StarlingX Documentation
+
* '''stx-docs:''' StarlingX Documentation
−
* stx-python-cinderclient   // i.e. only StarlingX-specific extensions to Cinder API are documented here
+
** '''stx-python-cinderclient'''  // i.e. only StarlingX-specific extensions to Cinder API are documented here
−
* stx-nova                          // i.e. only StarlingX-specific extensions to Nova API are documented here
+
** '''stx-nova'''                           // i.e. only StarlingX-specific extensions to Nova API are documented here
−
* stx-glance                        // i.e. only StarlingX-specific extensions to Glance API are documented here
+
** '''stx-glance'''                       // i.e. only StarlingX-specific extensions to Glance API are documented here
−
* stx-neutron                      // i.e. only StarlingX-specific extensions to Neutron API are documented here
+
** '''stx-neutron'''                     // i.e. only StarlingX-specific extensions to Neutron API are documented here
−
* stx-distcloud: StarlingX Distributed Cloud
+
* '''stx-distcloud:''' StarlingX Distributed Cloud
−
* stx-fault: StarlingX Fault Management
+
* '''stx-fault:''' StarlingX Fault Management
−
* stx-ha: StarlingX High Availability/Process Monitoring/Service Management
+
* '''stx-ha:''' StarlingX High Availability/Process Monitoring/Service Management
−
* stx-metal: StarlingX Bare Metal and Node Management, Hardware Maintenance
+
* '''stx-metal:''' StarlingX Bare Metal and Node Management, Hardware Maintenance
−
* stx-nfv: StarlingX NFVI Orchestration
+
* '''stx-nfv:''' StarlingX NFVI Orchestration
  
−
<!--
 
  
 
</Proposal>
 
</Proposal>
Line 29: Line 33:
 
<Proposal>
 
<Proposal>
  
−
-->
+
== Directory Structures ==
  
−
The directory structure of the API Reference documentation under each StarlingX project repository is fixed. Here is an example showing
+
The directory structure of the API Reference documentation under each StarlingX project repository is fixed.
−
stx-config StarlingX System Configuration Management
+
Here is an example showing '''stx-config''' StarlingX System Configuration Management
  
−
stx-config/api-ref/
+
stx-config/api-ref/
−
└── source
+
└── source
−
    ├── api-ref-sysinv-v1-config.rst
+
    ├── api-ref-sysinv-v1-config.rst
−
    ├── conf.py
+
    ├── conf.py
−
    └── index.rst
+
    └── index.rst
  
 
The initial modifications and additions to enable the API Documentation service in each StarlingX project are as follows:
 
The initial modifications and additions to enable the API Documentation service in each StarlingX project are as follows:
  
−
.gitignore modifications to ignore the building directories and HTML files for the API reference
+
*'''.gitignore''' modifications to ignore the building directories and HTML files for the API reference
−
.zuul.yaml modifications to add the jobs to build and publish the api-ref document
+
* '''.zuul.yaml''' modifications to add the jobs to build and publish the api-ref document
−
api-ref/source directory creation to store your API Reference project directory
+
* '''api-ref/source''' directory creation to store your API Reference project directory
−
api-ref/source/conf.py configuration file to determine the HTML theme, Sphinx extensions and project information
+
* '''api-ref/source/conf.py''' configuration file to determine the HTML theme, Sphinx extensions and project information
−
api-ref/source/index.rst source file to create your index RST source file
+
* '''api-ref/source/index.rst''' source file to create your index RST source file
−
doc/requiremets.txt modifications to add the os-api-ref Sphinx extension
+
* '''doc/requiremets.txt''' modifications to add the os-api-ref Sphinx extension
−
tox.ini modifications to add the configuration to build the API reference locally
+
* '''tox.ini''' modifications to add the configuration to build the API reference locally
  
 
See stx-config [Doc] OpenStack API Reference Guide as an example of this first commit:
 
See stx-config [Doc] OpenStack API Reference Guide as an example of this first commit:
 
https://review.openstack.org/#/c/603258/
 
https://review.openstack.org/#/c/603258/
  
−
Once the API Documentation service has been enabled, you create the RST source files that document  the API operations under the same API Reference documentation project directory.
+
== Creating the RST Source File ==
−
The following shows the RST source file for the stx-config StarlingX System Configuration Management: Configuration API v1
 
  
−
stx-config/api-ref/
+
Once the API Documentation service has been enabled, you create the RST source files that document 
−
└── source
+
the API operations under the same API Reference documentation project directory.
−
    └── api-ref-sysinv-v1-config.rst
+
The following shows the RST source file for the '''stx-config''' StarlingX System Configuration Management: Configuration API v1
  
−
</Proposal>
+
stx-config/api-ref/
 +
└── source
 +
    └── api-ref-sysinv-v1-config.rst
 +
 
 +
== Creating the Index File ==
  
−
After providing the RST source file as shown in the previous example, you add the index.rst file.
+
After providing the RST source file as shown in the previous example, you add the '''index.rst''' file.
 
This file provides captioning, a brief description of the document, and the table-of-contents structure with depth restrictions.
 
This file provides captioning, a brief description of the document, and the table-of-contents structure with depth restrictions.
−
The index.rst file resides in the same folder as the RST source file.
+
The '''index.rst''' file resides in the same folder as the RST source file.
−
Here is an example using the stx-config StarlingX System Configuration Management: Configurationi API v1:
 
  
−
stx-config/api-ref/
+
Here is an example using the '''stx-config''' StarlingX System Configuration Management: Configurationi API v1:
−
|___source
 
−
  |___api-ref-sysinv-v1-config.rst
 
−
  |___index.rst
 
  
−
The syntax of the index.rst file is fixed.
+
stx-config/api-ref/
−
Following shows the index.rst file used in the stx-config:
+
|___source
 +
  |___api-ref-sysinv-v1-config.rst
 +
  |___index.rst
  
−
========================
+
The syntax of the '''index.rst''' file is fixed.
−
stx-config API Reference
+
Following shows the '''index.rst''' file used in the '''stx-config''':
−
========================
 
  
−
StarlingX System Configuration Management
+
========================
 +
stx-config API Reference
 +
========================
  
−
.. toctree::
+
StarlingX System Configuration Management
−
  :maxdepth: 2
 
  
−
  api-ref-sys-v1-config
+
.. toctree::
 +
    :maxdepth: 2
  
−
Following are explanations for each of the four areas of the index.rst file:
+
    api-ref-sys-v1-config
−
Reference title:  Literal title that is used in the rendered document.  In this case it is "stx-config API Reference".
 
−
Reference summary: Literal summary of the rendered document.  In this case it is "StarlingX System Configuration Management".
 
−
Table-of-Contents tree structure and depth parameters:  The directive to create a TOC and to limit the depth of topics to "2".
 
−
RST source file root name: The source file to use as content.  In this case, the file reference is "api-ref-sys-v1-config".  This references the api-ref-sys-v1-config.rst file in the same folder as the index.rst file.
 
  
 +
Following are explanations for each of the four areas of the '''index.rst''' file:
 +
* '''Reference title:'''  Literal title that is used in the rendered document.  In this case it is "stx-config API Reference".
 +
* '''Reference summary:''' Literal summary of the rendered document.  In this case it is "StarlingX System Configuration Management".
 +
* '''Table-of-Contents tree structure and depth parameters:'''  The directive to create a TOC and to limit the depth of topics to "2".
 +
* '''RST source file root name:''' The source file to use as content.  In this case, the file reference is "api-ref-sys-v1-config".  This references the '''api-ref-sys-v1-config.rst''' file in the same folder as the '''index.rst''' file.
  
−
<Proposal>
+
== REST METHOD Syntax ==
  
−
... ??? is there not any existing web page from docs.openstack.org on this syntax ???
+
Following is the syntax for each REST METHOD in the RST source file (e.g. '''api-ref-sys-v1-config.rst''').
−
IF NOT,
 
−
- maybe have to provide our own description of major sections of rest api documentation
 
  
−
Following is the syntx for each REST METHOD in the RST source file (e.g. api-ref-sys-v1-config.rst).
+
******************************************
−
 
+
Modifies attributes of the System object
−
******************************************
+
******************************************
−
Modifies attributes of the System object
 
−
******************************************
 
 
   
 
   
−
.. rest_method:: PATCH /v1/isystems
+
.. rest_method:: PATCH /v1/isystems
  
−
<  TEXT - description of the overall REST API >
+
<  TEXT - description of the overall REST API >
  
−
**Normal response codes**
+
**Normal response codes**
  
−
< TEXT - list of normal response codes  >
+
< TEXT - list of normal response codes  >
  
−
**Error response codes**
+
**Error response codes**
  
−
< TEXT – list of  error response codes  >
+
< TEXT – list of  error response codes  >
  
−
**Request parameters**
+
**Request parameters**
  
−
.. csv-table::
+
.. csv-table::
−
  :header: "Parameter", "Style", "Type", "Description"
+
    :header: "Parameter", "Style", "Type", "Description"
−
  :widths: 20, 20, 20, 60
+
    :widths: 20, 20, 20, 60
−
  "ihosts (Optional)", "plain", "xsd:list", "Links for retreiving the list of hosts for this system."
+
    "ihosts (Optional)", "plain", "xsd:list", "Links for retreiving the list of hosts for this system."
−
  "name (Optional)", "plain", "xsd:string", "A user-specified name of the cloud system. The default value is the system UUID."
+
    "name (Optional)", "plain", "xsd:string", "A user-specified name of the cloud system. The default value is the system UUID."
−
  < etc. >
+
    < etc. >
−
::
 
−
  < verbatim list of an example REQUEST body >
 
−
  [
 
−
    {
 
−
      "path": "/name",
 
−
      "value": "OTTAWA_LAB_WEST",
 
−
      "op": "replace"
 
−
    }
 
−
    {
 
−
      "path": "/description",
 
−
      "value": "The Ottawa Cloud Test Lab - West Wing.",
 
−
      "op": "replace"
 
−
    }
 
−
  ]
 
  
−
**Response parameters**
+
::
  
−
.. csv-table::
+
    < verbatim list of an example REQUEST body >
−
  :header: "Parameter", "Style", "Type", "Description"
+
    [
−
  :widths: 20, 20, 20, 60
+
      {
−
  "ihosts (Optional)", "plain", "xsd:list", "Links for retreiving the list of hosts for this system."
+
        "path": "/name",
−
  "name (Optional)", "plain", "xsd:string", "A user-specified name of the cloud system. The default value is the system UUID."
+
        "value": "OTTAWA_LAB_WEST",
−
  < etc. >
+
        "op": "replace"
 +
      }
 +
      {
 +
        "path": "/description",
 +
        "value": "The Ottawa Cloud Test Lab - West Wing.",
 +
        "op": "replace"
 +
      }
 +
    ]
  
−
::
+
**Response parameters**
−
  < verbatim list of an example RESPONSE body >
 
−
  {
 
−
    "isystems": [
 
−
      {
 
−
        "links": [
 
−
          {
 
−
            "href": "http://192.168.204.2:6385/v1/isystems/5ce48a37-f6f5-4f14-8fbd-ac6393464b19",
 
−
            "rel": "self"
 
−
          },
 
−
          {
 
−
            "href": "http://192.168.204.2:6385/isystems/5ce48a37-f6f5-4f14-8fbd-ac6393464b19",
 
−
            "rel": "bookmark"
 
−
          }
 
−
        ],
 
−
        "description": "The Ottawa Cloud Test Lab - West Wing.",
 
−
        "software_version": "18.03",
 
−
        "updated_at": "2017-07-31T17:44:06.051441+00:00",
 
−
        "created_at": "2017-07-31T17:35:46.836024+00:00",
 
−
        }
 
−
    ]
 
−
  }
 
  
−
</Proposal>
+
.. csv-table::
 +
    :header: "Parameter", "Style", "Type", "Description"
 +
    :widths: 20, 20, 20, 60
 +
    "ihosts (Optional)", "plain", "xsd:list", "Links for retreiving the list of hosts for this system."
 +
    "name (Optional)", "plain", "xsd:string", "A user-specified name of the cloud system. The default value is the system UUID."
 +
    < etc. >
  
 +
::
  
−
Explain what the ‘tox -e api-ref’ command is doing
+
    < verbatim list of an example RESPONSE body >
−
Is this building the API DOC html and pdf ? (dtroyer) It builds the html, PDF build is a different tox environment (where it exists)
+
    {
−
Explain how to look at the finished HTML or PDF files to verify their change.
+
      "isystems": [
−
(dtroyer) the build output is in api-ref/build/html, you can just load index.html into a browser and look at it locally. If the job has run in Gerrit, click on the job name in the Gerrit review page (the list on the right side of the screen below the reviewers) and it will show the renered pages if the job was successful
+
        {
 +
          "links": [
 +
            {
 +
              "href": "http://192.168.204.2:6385/v1/isystems/5ce48a37-f6f5-4f14-8fbd-ac6393464b19",
 +
              "rel": "self"
 +
            },
 +
            {
 +
              "href": "http://192.168.204.2:6385/isystems/5ce48a37-f6f5-4f14-8fbd-ac6393464b19",
 +
              "rel": "bookmark"
 +
            }
 +
          ],
 +
          "description": "The Ottawa Cloud Test Lab - West Wing.",
 +
          "software_version": "18.03",
 +
          "updated_at": "2017-07-31T17:44:06.051441+00:00",
 +
          "created_at": "2017-07-31T17:35:46.836024+00:00",
 +
        }
 +
      ]
 +
    }
  
−
<Proposal>
+
== Building the Reference Documentation ==
  
 
To build the API reference documentation locally in HTML format, use the following command:
 
To build the API reference documentation locally in HTML format, use the following command:
  
−
$ tox -e api-ref
+
$ tox -e api-ref
  
 
The resulting directories and HTML files looks like:
 
The resulting directories and HTML files looks like:
  
−
api-ref
+
api-ref
−
|__build/
+
|__build/
−
├── doctrees
+
├── doctrees
−
│  ├── api-ref-sysinv-v1-config.doctree
+
│  ├── api-ref-sysinv-v1-config.doctree
 +
      ...
 +
└── html
 +
    ├── api-ref-sysinv-v1-config.html
 +
    ├── index.html
 
       ...
 
       ...
−
└── html
+
    └── _static
−
    ├── api-ref-sysinv-v1-config.html
+
 
−
    ├── index.html
+
== Viewing the Rendered Reference Documentation ==
−
    ...
 
−
    └── _static
 
  
−
To view the rendered HTML API Reference document in a browser, open up the index.html file.
+
To view the rendered HTML API Reference document in a browser, open up the '''index.html''' file.
  
−
NOTE:  The PDF build uses a different tox environment and is currently not supported for StarlingX.  
+
'''NOTE:''' The PDF build uses a different tox environment and is currently not supported for StarlingX.
  
−
</Proposal>
+
-->

Latest revision as of 18:13, 25 October 2018


See the StarlingX API Contributor Guide for information on contributing to StarlingX API documentation. This wiki page has been deprecated.


Retrieved from "https://wiki.openstack.org/w/index.php?title=StarlingX/Designer_REST_API_Documentation&oldid=166299"