86 lines
3.0 KiB
ReStructuredText
86 lines
3.0 KiB
ReStructuredText
API Documentation
|
|
=================
|
|
|
|
By providing guidelines for API documentation for all OpenStack services,
|
|
projects use common tooling, consistent outlines, and study exemplary examples
|
|
to meet expectations for API documentation.
|
|
|
|
Content
|
|
-------
|
|
|
|
First you should generate or write the reference information including:
|
|
|
|
- Method (GET/PUT/POST/PATCH/HEAD/DELETE)
|
|
- Resource (Identified by the URL)
|
|
- Request parameters, type and description including whether it
|
|
is optional
|
|
- Request headers including media-type, content-type, accept, and others
|
|
- Response headers (for some APIs)
|
|
- Responses including types and description
|
|
- Example request body and headers
|
|
- Example response body and headers
|
|
- Status codes: successful request and error responses
|
|
- Resource model: describes data types that can be consumed and produced by
|
|
operations.
|
|
|
|
The resource model may be created with either a parameters.yaml file or with
|
|
the `OpenAPI Definitions object <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#definitionsObject>`_
|
|
Swagger is governed by the OpenAPI initiative.
|
|
|
|
See authoring tools below for more information on writing or generating the
|
|
parameters information.
|
|
|
|
Also important is the conceptual or narrative information that explains the
|
|
REST API and what it provides as a service.
|
|
|
|
Documentation should also offer information about the concepts for each
|
|
resource, such as server status or volume status.
|
|
|
|
Documentation should provide a discussion about the consistency model the
|
|
service provides and synchronous or asynchronous behavior for certain methods.
|
|
|
|
As guidance, here is a list of topics to ensure you include in your API docs
|
|
beyond the reference information.
|
|
|
|
* Authentication
|
|
* Faults (synchronous and asynchronous)
|
|
* Limits (rate limits, absolute limits, calls to find out limits)
|
|
* Constraints (min and max for certain values even if chosen by provider)
|
|
* Content compression
|
|
* Encoding
|
|
* Links and references
|
|
* Pagination
|
|
* Filtering
|
|
* Sorting
|
|
* Formats (request, response)
|
|
* Endpoints, versions and discoverability
|
|
* Capabilities and discoverability
|
|
* Term definitions
|
|
(by adding to the OpenStack glossary sourced in openstack-manuals)
|
|
* Status or state values
|
|
* Hierarchy information
|
|
* Quotas
|
|
* Extensions
|
|
|
|
These topics should be written in RST and built with either Sphinx or alongside
|
|
the generated OpenAPI using the Pecan app described below. The outline itself
|
|
is not prescribed since REST APIs vary widely.
|
|
|
|
Authoring tools
|
|
---------------
|
|
|
|
The API documentation authoring tools are described in the
|
|
`Contributor Guide <http://docs.openstack.org/contributor-guide/api-guides.html>`_.
|
|
|
|
Publishing tools
|
|
----------------
|
|
|
|
The existing OpenStack infrastructure provides publishing to docs.openstack.org
|
|
and developer.openstack.org and specs.openstack.org from RST/Sphinx. In the
|
|
nova repo, for example, running `tox -e api-ref` builds Sphinx-based API
|
|
reference documentation locally.
|
|
|
|
For publishing OpenAPI-based reference, refer to
|
|
https://review.opendev.org/#/c/286659/ as an example that can be used in the
|
|
project repo.
|