Added more details to usage.rst
-Added info on max_version field. -Added info about including sample files. -Added warning test for missing lookup key. -Added warning test for missing type field. Change-Id: I1ffa2d3e1d425239641adbdf029647e1af72bca0
This commit is contained in:
parent
f5c3d79fe3
commit
b170c0016a
|
@ -1,5 +1,5 @@
|
|||
Usage
|
||||
========
|
||||
=====
|
||||
|
||||
``os-api-ref`` is designed to be used inside of a sphinx tree that is
|
||||
devoted solely to the documentation of the API.
|
||||
|
@ -33,6 +33,7 @@ a particular REST method. It takes the form of:
|
|||
|
||||
.. rest_method:: <METHODNAME> <url>
|
||||
|
||||
``METHODNAME`` should be one of the commonly used REST methods or HTTP verbs.
|
||||
This stanza should be the first element in a ``section`` that has some
|
||||
descriptive title about the method. An example from the Nova
|
||||
documentation is:
|
||||
|
@ -70,20 +71,22 @@ in ``rst``.
|
|||
|
||||
A REST API that uses JSON has a large number of structured parameters
|
||||
that include type, location (i.e. is this in the query, the header,
|
||||
the path, the body?), whether or not this is required, as well as the
|
||||
desire to have long description about each one. And, assuming some
|
||||
consistent modeling, that parameter will show up in multiple calls. A
|
||||
the path, the body), whether or not this parameter is required, as well as
|
||||
the desire to provide a long description about each parameter. And, assuming
|
||||
some consistent modeling, that parameter will show up in multiple calls. A
|
||||
``server_id`` used in the path is always going to have the same
|
||||
meaning.
|
||||
|
||||
It is natural to want to display this data in a tabular way to show
|
||||
all these dimensions. However, tables in RST are quite cumbersome, and
|
||||
all these dimensions. However, tables in ``rst`` are quite cumbersome, and
|
||||
repeating the same data over and over again is error prone.
|
||||
|
||||
``rest_parameters`` solves this by having the inline markup be a yaml
|
||||
list of ``name: value`` pairs. ``name`` is the name of the
|
||||
parameter. ``value`` is the key to lookup the rest of the details in a
|
||||
yaml file, specified in each stanza.
|
||||
The ``rest_parameters`` stanza solves this by having the inline markup
|
||||
be a yaml list of ``name: value`` pairs. ``name`` is the name of the
|
||||
parameter. ``value`` is the key to lookup the rest of the details for
|
||||
this parameter in a parameters file. In each method,
|
||||
there should be one ``rest_parameters`` stanza for the request, and
|
||||
another ``rest_parameters`` stanza for the response.
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
|
@ -148,8 +151,9 @@ parameters file format
|
|||
----------------------
|
||||
|
||||
The parameters file is inspired by the OpenAPI (aka: Swagger)
|
||||
specification for parameter specification. The following fields exist
|
||||
for every entry:
|
||||
specification. The OpenAPI specification provides a property object
|
||||
which categorizes the parameters by type and describes how the parameter is used.
|
||||
The following fields exist for every entry:
|
||||
|
||||
in
|
||||
where this parameter exists. One of ``header``, ``path``,
|
||||
|
@ -173,6 +177,10 @@ min_version
|
|||
the microversion that this parameter was introduced at. Will render
|
||||
a *new in $version* stanza in the html output.
|
||||
|
||||
max_version
|
||||
the last version that includes this parameter. Will render
|
||||
a *Deprecated in $version* stanza in the html output.
|
||||
|
||||
|
||||
rest_expand_all
|
||||
---------------
|
||||
|
@ -181,26 +189,44 @@ The ``rest_expand_all`` stanza is used to place a control in the
|
|||
document that will be a global Show / Hide for all sections. There are
|
||||
times when this is extremely nice to have.
|
||||
|
||||
|
||||
Including Sample Files
|
||||
======================
|
||||
|
||||
To refer to a sample file in a ``rst`` file, use the
|
||||
``rst`` directive, ``literalinclude``. Typically, the content sent
|
||||
or received is of type JSON, so the language role is set to javascript.
|
||||
The example immediately follows the parameter listing in the ``rst`` file.
|
||||
An example of an included Nova response sample file:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. literalinclude:: ../../doc/api_samples/os-evacuate/server-evacuate-resp.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Runtime Warnings
|
||||
================
|
||||
|
||||
The extension tries to help when it can point out that something isn't
|
||||
The extension tries to help when it can by pointing out that something isn't
|
||||
matching up correctly. The following warnings are generated when
|
||||
issues are found:
|
||||
|
||||
* parameters file is not found or parsable yaml
|
||||
* a lookup value in the parameters file is not found
|
||||
* the parameters file is not sorted
|
||||
* parameters file is not found
|
||||
* parameters file is not valid yaml, i.e.
|
||||
missing colon after the name
|
||||
* a lookup value in the ``rst`` file is not found in the parameters file
|
||||
* the parameters file is not sorted as outlined in the rules below
|
||||
|
||||
The sorting rules for parameters file is that first elements should be
|
||||
sorted by ``in`` going from earliest to latest processed.
|
||||
sorted by ``in``, going from earliest to latest processed.
|
||||
|
||||
#. header
|
||||
#. path
|
||||
#. query
|
||||
#. body
|
||||
|
||||
After that the parameters should be sorted by name, lower case alpha
|
||||
After that, the parameters should be sorted by name, lower case alpha
|
||||
numerically.
|
||||
|
||||
The sort enforcement is because in large parameters files it helps
|
||||
|
|
|
@ -11,3 +11,5 @@ I am text, hear me roar!
|
|||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- name: name
|
||||
- name: lookup_key_name
|
||||
- name: name_1
|
||||
|
|
|
@ -11,3 +11,8 @@ name:
|
|||
type: string
|
||||
description: |
|
||||
The name of things
|
||||
name_1:
|
||||
description: |
|
||||
name_1 is missing type field.
|
||||
in: body
|
||||
required: true
|
||||
|
|
|
@ -50,3 +50,19 @@ class TestWarnings(base.TestCase):
|
|||
("WARNING: Parameters out of order ``name2`` "
|
||||
"should be after ``name``"),
|
||||
self.warning)
|
||||
|
||||
def test_missing_lookup_name(self):
|
||||
"""Warning when missing lookup key in parameter file."""
|
||||
self.assertIn(
|
||||
("WARNING: No field definition for ``lookup_key_name`` found in "),
|
||||
self.warning)
|
||||
|
||||
def test_missing_field(self):
|
||||
"""Warning when missing type field in parameter file."""
|
||||
self.assertIn(
|
||||
("WARNING: Failure on key: name, values: "
|
||||
+ "OrderedDict([('description',"
|
||||
+ " 'name_1 is missing type field.\\n'), ('in', 'body'),"
|
||||
+ " ('required', True)]). "
|
||||
+ "'NoneType' object has no attribute 'split'\n"),
|
||||
self.warning)
|
||||
|
|
Loading…
Reference in New Issue