Start Designate API-Ref style documentation

Creates api-ref test env
Add basic v2/zones API documentation

Change-Id: I1783234c59319fdcb13b0df90f662253e822bab3
Depends-On: I0e615d36a2e5a8fa0d83f20bdcc2c33ad868ebd5

.gitignore

@@ -50,5 +50,6 @@ designate/versioninfo
 dist
 doc/build/*
 doc/source/api/*
+api-ref/build/*
 etc/designate/*.conf
 var/*

api-ref/source/_static/api-site.css

@@ -0,0 +1,81 @@
+tt.literal {
+    padding: 2px 4px;
+    font-size: 90%;
+    color: #c7254e;
+    white-space: nowrap;
+    background-color: #f9f2f4;
+    border-radius: 4px;
+}
+
+/* bootstrap users blockquote for pull quotes, so they are much
+larger, we need them smaller */
+blockquote { font-size: 1em; }
+
+pre {
+    display: block;
+    padding: 9.5px;
+    margin: 0 0 10px;
+    font-size: 13px;
+    line-height: 1.428571429;
+    color: #333;
+    word-break: break-all;
+    word-wrap: break-word;
+    background-color: #f5f5f5;
+    border: 1px solid #ccc;
+    border-radius: 4px;
+}
+
+tbody>tr:nth-child(odd)>td,
+tbody>tr:nth-child(odd)>th {
+    background-color: #f9f9f9;
+}
+
+table>thead>tr>th, table>tbody>tr>th, table>tfoot>tr>th, table>thead>tr>td, table>tbody>tr>td, table>tfoot>tr>td {
+    padding: 8px;
+    line-height: 1.428571429;
+    vertical-align: top;
+    border-top: 1px solid #ddd;
+}
+
+td>p {
+    margin: 0 0 0.5em;
+}
+
+div.document {
+    width: 80% !important;
+}
+
+@media (max-width: 1200px) {
+    div.document {
+        width: 960px !important;
+    }
+}
+
+.operation-grp {
+    padding-top: 0.5em;
+    padding-bottom: 1em;
+}
+
+/* Ensure the method buttons and their links don't split lines when
+the page is narrower */
+.operation {
+    /* this moves the link icon into the gutter */
+    margin-left: -1.25em;
+    margin-right: 1.25em;
+    white-space: nowrap;
+}
+
+/* These make the links only show up on hover */
+a.operation-anchor {
+  visibility: hidden;
+}
+
+.operation-grp:hover a.operation-anchor {
+  visibility: visible;
+}
+
+/* All tables for requests should be full width */
+
+.api-detail table.docutils {
+    width: 100%;
+}

api-ref/source/_static/api-site.js

@@ -0,0 +1,110 @@
+(function() {
+
+  var pageCache;
+
+  $(document).ready(function() {
+    pageCache = $('.api-documentation').html();
+
+    // Show the proper JSON/XML example when toggled
+    $('.example-select').on('change', function(e) {
+      $(e.currentTarget).find(':selected').tab('show')
+    });
+
+    // Change the text on the expando buttons when appropriate
+    $('.api-detail')
+      .on('hide.bs.collapse', function(e) {
+        processButton(this, 'detail');
+      })
+      .on('show.bs.collapse', function(e) {
+        processButton(this, 'close');
+      });
+
+    var expandAllActive = true;
+     // Expand the world
+    $('#expand-all').click(function () {
+        if (expandAllActive) {
+            expandAllActive = false;
+            $('.api-detail').collapse('show');
+            $('#expand-all').attr('data-toggle', '');
+            $(this).text('Hide All');
+        } else {
+            expandAllActive = true;
+            $('.api-detail').collapse('hide');
+            $('#expand-all').attr('data-toggle', 'collapse');
+            $(this).text('Show All');
+        }});
+
+    // Wire up the search button
+    $('#search-btn').on('click', function(e) {
+      searchPage();
+    });
+
+    // Wire up the search box enter
+    $('#search-box').on('keydown', function(e) {
+      if (e.keyCode === 13) {
+        searchPage();
+        return false;
+      }
+    });
+  });
+
+  /**
+   * highlight terms based on the regex in the provided $element
+   */
+  function highlightTextNodes($element, regex) {
+    var markup = $element.html();
+
+    // Do regex replace
+    // Inject span with class of 'highlighted termX' for google style highlighting
+    $element.html(markup.replace(regex, '>$1<span class="highlight">$2</span>$3<'));
+  }
+
+  function searchPage() {
+    $(".api-documentation").html(pageCache);
+
+    //make sure that all div's are expanded/hidden accordingly
+    $('.api-detail.in').each(function (e) {
+      $(this).collapse('hide');
+    });
+
+    var startTime = new Date().getTime(),
+      searchTerm = $('#search-box').val();
+
+    // The regex is the secret, it prevents text within tag declarations to be affected
+    var regex = new RegExp(">([^<]*)?(" + searchTerm + ")([^>]*)?<", "ig");
+    highlightTextNodes($('.api-documentation'), regex);
+
+    // Once we've highlighted the node, lets expand any with a search match in them
+    $('.api-detail').each(function () {
+
+      var $elem = $(this);
+
+      if ($elem.html().indexOf('<span class="highlight">') !== -1) {
+        $elem.collapse('show');
+        processButton($elem, 'close');
+      }
+    });
+
+    // log the results
+    if (console.log) {
+      console.log("search completed in: " + ((new Date().getTime()) - startTime) + "ms");
+    }
+
+    $('.api-detail')
+      .on('hide.bs.collapse', function (e) {
+        processButton(this, 'detail');
+      })
+      .on('show.bs.collapse', function (e) {
+        processButton(this, 'close');
+      });
+  }
+
+  /**
+   * Helper function for setting the text, styles for expandos
+   */
+  function processButton(button, text) {
+    $('#' + $(button).attr('id') + '-btn').text(text)
+      .toggleClass('btn-info')
+      .toggleClass('btn-default');
+  }
+})();

api-ref/source/conf.py

@@ -0,0 +1,216 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+# ironic documentation build configuration file, created by
+# sphinx-quickstart on Sat May  1 15:17:47 2010.
+#
+# This file is execfile()d with the current directory set to
+# its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import os
+import subprocess
+import sys
+
+from designate.version import version_info
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('../../'))
+sys.path.insert(0, os.path.abspath('../'))
+sys.path.insert(0, os.path.abspath('./'))
+
+# -- General configuration ----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+
+extensions = [
+    'os_api_ref',
+    'oslosphinx',
+]
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#
+# source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Designate API Reference'
+copyright = u'OpenStack Foundation'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The full version, including alpha/beta/rc tags.
+release = version_info.release_string()
+# The short X.Y version.
+version = version_info.version_string()
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+# today = ''
+# Else, today_fmt is used as the format for a strftime call.
+# today_fmt = '%B %d, %Y'
+
+# The reST default role (used for this markup: `text`) to use
+# for all documents.
+# default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = False
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for man page output ----------------------------------------------
+
+# Grouping the document tree for man pages.
+# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
+
+
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+# html_theme_path = ["."]
+# html_theme = '_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+# html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+# html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+# html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+# html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+# html_last_updated_fmt = '%b %d, %Y'
+git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
+           "-n1"]
+html_last_updated_fmt = subprocess.Popen(
+    git_cmd, stdout=subprocess.PIPE).communicate()[0]
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+# html_use_modindex = True
+
+# If false, no index is generated.
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+# html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+# html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'designatedoc'
+
+
+# -- Options for LaTeX output -------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+# latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+# latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    ('index', 'Designate.tex', u'OpenStack DNS API Documentation',
+     u'OpenStack Foundation', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+# latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+# latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+# latex_appendices = []
+
+# If false, no module index is generated.
+# latex_use_modindex = True

api-ref/source/dns-api-v2-zone.inc

@@ -0,0 +1,307 @@
+====
+Zone
+====
+
+Zone operations.
+
+
+Create Zone
+===========
+
+.. rest_method::  POST /v2/zones
+
+Create a zone
+
+
+Normal response codes: 201
+Error response codes:405,404,403,401,400,503,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - name: zone_name
+   - email: zone_email
+   - ttl: zone_ttl
+   - description: zone_description
+   - type: zone_type
+
+
+Request Example
+---------------
+
+.. literalinclude:: samples/zones/create-zone-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - id: id
+   - pool_id: zone_pool_id
+   - project_id: project_id
+   - name: zone_name
+   - email: zone_email
+   - ttl: zone_ttl
+   - serial: zone_serial
+   - status: status
+   - action: action
+   - description: zone_description
+   - masters: zone_masters
+   - type: zone_type
+   - transfered_at: zone_transfered_at
+   - version: version
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/zones/zone-response.json
+   :language: javascript
+
+
+List Zones
+==========
+
+.. rest_method::  GET /v2/zones
+
+Show a zone
+
+
+Normal response codes: 200
+Error response codes:405,404,403,401,400,503,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - limit: limit
+   - marker: marker
+   - sort_dir: sort_dir
+   - sort_key: sort_key
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - id: id
+   - pool_id: zone_pool_id
+   - project_id: project_id
+   - name: zone_name
+   - email: zone_email
+   - ttl: zone_ttl
+   - serial: zone_serial
+   - status: status
+   - action: action
+   - description: zone_description
+   - masters: zone_masters
+   - type: zone_type
+   - transfered_at: zone_transfered_at
+   - version: version
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/zones/list-zones-response.json
+   :language: javascript
+
+
+Show a Zone
+===========
+
+.. rest_method::  GET /v2/zones/{zone_id}
+
+Show a zone
+
+
+Normal response codes: 200
+Error response codes:405,404,403,401,400,503,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - zone_id: zone_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - id: id
+   - pool_id: zone_pool_id
+   - project_id: project_id
+   - name: zone_name
+   - email: zone_email
+   - ttl: zone_ttl
+   - serial: zone_serial
+   - status: status
+   - action: action
+   - description: zone_description
+   - masters: zone_masters
+   - type: zone_type
+   - transfered_at: zone_transfered_at
+   - version: version
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/zones/zone-response.json
+   :language: javascript
+
+
+Update a Zone
+=============
+
+.. rest_method::  PATCH /v2/zones/{zone_id}
+
+Show a zone
+
+
+Normal response codes: 201
+Error response codes:405,404,403,401,400,503,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - zone_id: zone_id
+   - email: zone_email_update
+   - ttl: zone_ttl
+   - description: zone_description
+
+
+Request Example
+---------------
+
+.. literalinclude:: samples/zones/update-zone-request.json
+   :language: javascript
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - id: id
+   - pool_id: zone_pool_id
+   - project_id: project_id
+   - name: zone_name
+   - email: zone_email
+   - ttl: zone_ttl
+   - serial: zone_serial
+   - status: status
+   - action: action
+   - description: zone_description
+   - masters: zone_masters
+   - type: zone_type
+   - transfered_at: zone_transfered_at
+   - version: version
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/zones/update-zone-response.json
+   :language: javascript
+
+
+Delete a Zone
+=============
+
+.. rest_method::  DELETE /v2/zones/{zone_id}
+
+Show a zone
+
+
+Normal response codes: 201
+Error response codes:405,404,403,401,400,503,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-auth-token: x-auth-token
+   - x-auth-all-projects: x-auth-all-projects
+   - x-auth-sudo-project-id: x-auth-sudo-project-id
+   - zone_id: zone_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - x-openstack-request-id: x-openstack-request-id
+   - id: id
+   - pool_id: zone_pool_id
+   - project_id: project_id
+   - name: zone_name
+   - email: zone_email
+   - ttl: zone_ttl
+   - serial: zone_serial
+   - status: status
+   - action: action
+   - description: zone_description
+   - masters: zone_masters
+   - type: zone_type
+   - transfered_at: zone_transfered_at
+   - version: version
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/zones/delete-zone-response.json
+   :language: javascript

api-ref/source/index.rst

@@ -0,0 +1,9 @@
+:tocdepth: 2
+
+========
+ DNS API
+========
+
+.. rest_expand_all::
+
+.. include:: dns-api-v2-zone.inc

api-ref/source/parameters.yaml

@@ -0,0 +1,282 @@
+#############################
+#     Common Variables      #
+#############################
+
+# Header Variables
+###################
+
+x-auth-token:
+  description: |
+    Token used to identify the user from keystone
+  in: header
+  required: false
+  type: string
+
+x-auth-all-projects:
+  description: |
+    If enabled this will show results from all projects in Designate
+  in: header
+  required: false
+  type: bool
+
+x-auth-sudo-project-id:
+  description: |
+    This allows a user to impersonate another project
+  in: header
+  required: false
+  type: string
+
+x-designate-edit-managed-records:
+  description: |
+    If enabled this will all users to edit records flagged as managed
+  in: header
+  required: false
+  type: bool
+
+x-openstack-request-id:
+  description: |
+    ID of the request
+  in: header
+  required: false
+  type: string
+
+# Path Variables
+#################
+
+
+# Query Variables
+##################
+
+limit:
+  description: |
+    Requests a page size of items. Returns a number
+    of items up to a limit value. Use the ``limit`` parameter to make
+    an initial limited request and use the ID of the last-seen item
+    from the response as the ``marker`` parameter value in a
+    subsequent limited request.
+  in: query
+  required: false
+  type: integer
+marker:
+  description: |
+    The ID of the last-seen item. Use the ``limit``
+    parameter to make an initial limited request and use the ID of the
+    last-seen item from the response as the ``marker`` parameter value
+    in a subsequent limited request.
+  in: query
+  required: false
+  type: string
+sort_dir:
+  description: |
+    Sorts the response by the requested sort
+    direction. A valid value is ``asc`` (ascending) or ``desc``
+    (descending). Default is ``asc``. You can specify multiple pairs
+    of sort key and sort direction query parameters. If you omit the
+    sort direction in a pair, the API uses the natural sorting
+    direction of the server attribute that is provided as the
+    ``sort_key``.
+  in: query
+  required: false
+  type: string
+sort_key:
+  description: |
+    Sorts the response by the this attribute value.
+    Default is ``id``. You can specify multiple pairs of sort key and
+    sort direction query parameters. If you omit the sort direction in
+    a pair, the API uses the natural sorting direction of the server
+    attribute that is provided as the ``sort_key``.
+  in: query
+  required: false
+  type: string
+
+# Body Variables
+#################
+
+
+id:
+  description: |
+    ID for the resource
+  in: body
+  required: true
+  type: uuid
+
+
+project_id:
+  description: |
+    ID for the project that owns the resource
+  in: body
+  required: true
+  type: uuid
+
+
+description:
+  description: |
+    Description for the resource. Only showen in API / Horizon
+  in: body
+  required: true
+  type: string
+
+version:
+  description: |
+    Version of the resource
+  in: body
+  required: true
+  type: integer
+
+
+created_at:
+  description: |
+    Date / Time when resource was created
+  in: body
+  required: true
+  type: datestamp
+
+updated_at:
+  description: |
+    Date / Time when resource last updated
+  in: body
+  required: true
+  type: datestamp
+
+status:
+  description: |
+    status of the resource
+  in: body
+  required: true
+  type: enum
+
+action:
+  description: |
+    current action in progress on the resource
+  in: body
+  required: true
+  type: enum
+
+links:
+  description: |
+    Links to the resource, and other related resources
+  in: body
+  required: true
+  type: object
+
+#############################
+#      Zone Variables       #
+#############################
+
+
+# Header Variables
+###################
+
+# Path Variables
+#################
+
+zone_id:
+  description: |
+    ID for the zone
+  in: path
+  required: true
+  type: string
+
+
+# Query Variables
+##################
+
+# Body Variables
+#################
+
+
+zone_name:
+  description: |
+    DNS Name for the zone
+  in: body
+  required: true
+  type: domainname
+
+zone_email:
+  description: |
+    e-mail for the zone. Used in SOA records for the zone
+  in: body
+  required: true
+  type: string
+
+zone_email_update:
+  description: |
+    e-mail for the zone. Used in SOA records for the zone
+  in: body
+  required: false
+  type: string
+
+zone_ttl:
+  description: |
+    TTL (Time to Live) for the zone.
+  in: body
+  required: false
+  type: integer
+
+zone_description:
+  description: |
+    Description for this zone
+  in: body
+  required: false
+  type: string
+
+zone_pool_id:
+  description: |
+    ID for the pool hosting this zone
+  in: body
+  required: true
+  type: uuid
+
+zone_serial:
+  description: |
+    current serial number for the zone
+  in: body
+  required: true
+  type: integer
+
+zone_serial:
+  description: |
+    current serial number for the zone
+  in: body
+  required: true
+  type: integer
+
+zone_type:
+  description: |
+    Type of zone. PRIMARY is controlled by Designate, SECONDARY zones are slaved from another DNS Server. Defaults to PRIMARY
+  in: body
+  required: false
+  type: enum
+
+zone_masters:
+  description: |
+    For secondary zones. The servers to slave from to get DNS information
+  in: body
+  required: true
+  type: enum
+
+zone_transfered_at:
+  description: |
+    For secondary zones. The last time an update was retrived from the master servers
+  in: body
+  required: true
+  type: enum
+
+
+
+#############################
+#      <ITEM> Variables       #
+#############################
+
+
+# Header Variables
+###################
+
+# Path Variables
+#################
+
+# Query Variables
+##################
+
+# Body Variables
+#################

api-ref/source/samples/zones/create-zone-request.json

@@ -0,0 +1,7 @@
+{
+    "name": "example.org.",
+    "email": "joe@example.org",
+    "type": "PRIMARY",
+    "ttl": 7200,
+    "description": "This is an example zone."
+}

api-ref/source/samples/zones/delete-zone-response.json

@@ -0,0 +1,21 @@
+{
+    "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3",
+    "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2",
+    "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66",
+    "name": "example.org.",
+    "email": "joe@example.org",
+    "ttl": 600,
+    "serial": 1404757531,
+    "status": "PENDING",
+    "action": "DELETE",
+    "description": "Updated Description",
+    "masters": [],
+    "type": "PRIMARY",
+    "transferred_at": null,
+    "version": 1,
+    "created_at": "2014-07-07T18:25:31.275934",
+    "updated_at": null,
+    "links": {
+      "self": "https://127.0.0.1:9001/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3"
+    }
+}

api-ref/source/samples/zones/list-zones-response.json

@@ -0,0 +1,25 @@
+{
+    "zones": [
+        {
+            "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3",
+            "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2",
+            "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66",
+            "name": "example.org.",
+            "email": "joe@example.org",
+            "ttl": 7200,
+            "serial": 1404757531,
+            "status": "ACTIVE",
+            "action": "CREATE",
+            "description": "This is an example zone.",
+            "masters": [],
+            "type": "PRIMARY",
+            "transferred_at": null,
+            "version": 1,
+            "created_at": "2014-07-07T18:25:31.275934",
+            "updated_at": null,
+            "links": {
+              "self": "https://127.0.0.1:9001/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3"
+            }
+        }
+    ]
+}

api-ref/source/samples/zones/update-zone-request.json

@@ -0,0 +1,4 @@
+{
+    "ttl": 600,
+    "description": "Updated Description"
+}

api-ref/source/samples/zones/update-zone-response.json

@@ -0,0 +1,21 @@
+{
+    "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3",
+    "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2",
+    "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66",
+    "name": "example.org.",
+    "email": "joe@example.org",
+    "ttl": 600,
+    "serial": 1404757531,
+    "status": "PENDING",
+    "action": "UPDATE",
+    "description": "Updated Description",
+    "masters": [],
+    "type": "PRIMARY",
+    "transferred_at": null,
+    "version": 1,
+    "created_at": "2014-07-07T18:25:31.275934",
+    "updated_at": null,
+    "links": {
+      "self": "https://127.0.0.1:9001/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3"
+    }
+}

api-ref/source/samples/zones/zone-response.json

@@ -0,0 +1,21 @@
+{
+    "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3",
+    "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2",
+    "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66",
+    "name": "example.org.",
+    "email": "joe@example.org",
+    "ttl": 7200,
+    "serial": 1404757531,
+    "status": "ACTIVE",
+    "action": "CREATE",
+    "description": "This is an example zone.",
+    "masters": [],
+    "type": "PRIMARY",
+    "transferred_at": null,
+    "version": 1,
+    "created_at": "2014-07-07T18:25:31.275934",
+    "updated_at": null,
+    "links": {
+      "self": "https://127.0.0.1:9001/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3"
+    }
+}

test-requirements.txt

@@ -21,4 +21,5 @@ tempest-lib>=0.14.0 # Apache-2.0
 reno>=1.6.2 # Apache2
 # Bandit security code scanner
 bandit>=1.0.1 # Apache-2.0
+os-api-ref>=0.1.0  # Apache-2.0
 

tox.ini

@@ -98,6 +98,20 @@ passenv = TEMPEST_CONFIG
           OS_LOG_CAPTURE
           OS_DEBUG
 
+[testenv:api-ref]
+# This environment is called from CI scripts to test and publish
+# the API Ref to developer.openstack.org.
+# NOTE(sdague): this target does not use constraints because
+# upstream infra does not yet support it. Once that's fixed, we can
+# drop the install_command.
+#
+# we do not used -W here because we are doing some slightly tricky
+# things to build a single page document, and as such, we are ok
+# ignoring the duplicate stanzas warning.
+commands =
+  rm -rf api-ref/build
+  sphinx-build -E -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
+
 [testenv:releasenotes]
 # NOTE(kiall): this target does not use constraints because upstream infra does
 #              not yet support it. Once that's fixed, we can drop the