Fix parameters.yaml order

Also enabled "-W" flag to sphinx to ensure the file
stays in order going forward

Change-Id: I3817fc329096bbf10bdf69b2bbe4208ba1c142d1

2 files changed, 1203 insertions, 609 deletions

diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 6a65131a..f68852b1 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -1,16 +1,6 @@
-#############################
-#     Common Variables      #
-#############################
-
-# Header Variables
-###################
-
-x-auth-token:
-  description: |
-    Token used to identify the user from keystone
-  in: header
-  required: false
-  type: string
+####################
+# Header Variables #
+####################
 
 x-auth-all-projects:
   description: |
@@ -26,6 +16,13 @@ x-auth-sudo-project-id:
   required: false
   type: string
 
+x-auth-token:
+  description: |
+    Token used to identify the user from keystone
+  in: header
+  required: false
+  type: string
+
 x-designate-edit-managed-records:
   description: |
     If enabled this will all users to edit records flagged as managed
@@ -40,12 +37,22 @@ x-openstack-request-id:
   required: false
   type: string
 
-# Path Variables
-#################
+zone_export_accepts:
+  description: >
+    Content-Type that will be accepted by the client.
+    This endpoint will send a response with a ``text/dns`` content-type.
+    If the client does not include a ``Accepts: text/dns`` header
+  in: header
+  required: true
+  type: string
 
-path_zone_id:
+####################
+#  Path Variables  #
+####################
+
+path_pool_id:
   description: |
-    ID for the zone
+    ID for this pool
   in: path
   required: true
   type: uuid
@@ -57,8 +64,58 @@ path_recordset_id:
   required: true
   type: uuid
 
-# Query Variables
-##################
+path_zone_export_id:
+  description: |
+    ID for this zone export
+  in: path
+  required: true
+  type: uuid
+
+path_zone_id:
+  description: |
+    ID for the zone
+  in: path
+  required: true
+  type: uuid
+
+path_zone_import_id:
+  description: |
+    ID for this zone import
+  in: path
+  required: true
+  type: uuid
+
+path_zone_transfer_accept_id:
+  description: |
+    ID for this zone transfer accept
+  in: path
+  required: true
+  type: uuid
+
+path_zone_transfer_request_id:
+  description: |
+    ID for this zone transfer request
+  in: path
+  required: true
+  type: uuid
+
+tld_id:
+  description: |
+    ID for this tld
+  in: path
+  required: true
+  type: uuid
+
+tsigkey_id:
+  description: |
+    ID for this tsigkey
+  in: path
+  required: true
+  type: uuid
+
+####################
+# Query Variables  #
+####################
 
 limit:
   description: |
@@ -70,6 +127,7 @@ limit:
   in: query
   required: false
   type: integer
+
 marker:
   description: |
     The ID of the last-seen item. Use the ``limit``
@@ -79,6 +137,49 @@ marker:
   in: query
   required: false
   type: string
+
+recordset_data_filter:
+  description: |
+    Filter results to only show recordsets that have a record with data matching the filter
+  in: query
+  required: false
+  type: string
+
+recordset_description_filter:
+  description: |
+    Filter results to only show recordsets that have a description matching the filter
+  in: query
+  required: false
+  type: string
+
+recordset_name_filter:
+  description: |
+    Filter results to only show recordsets that have a name matching the filter
+  in: query
+  required: false
+  type: string
+
+recordset_status_filter:
+  description: |
+    Filter results to only show recordsets that have a status matching the filter
+  in: query
+  required: false
+  type: string
+
+recordset_ttl_filter:
+  description: |
+    Filter results to only show recordsets that have a ttl matching the filter
+  in: query
+  required: false
+  type: string
+
+recordset_type_filter:
+  description: |
+    Filter results to only show recordsets that have a type matching the filter
+  in: query
+  required: false
+  type: string
+
 sort_dir:
   description: |
     Sorts the response by the requested sort
@@ -91,6 +192,7 @@ sort_dir:
   in: query
   required: false
   type: string
+
 sort_key:
   description: |
     Sorts the response by the this attribute value.
@@ -102,119 +204,93 @@ sort_key:
   required: false
   type: string
 
-# Body Variables
-#################
-
-
-id:
+tld_name_filter:
   description: |
-    ID for the resource
-  in: body
-  required: true
-  type: uuid
-
+    Filter results to only show tlds that have a name matching the filter
+  in: query
+  required: false
+  type: string
 
-project_id:
+tsigkey_algorithm_filter:
   description: |
-    ID for the project that owns the resource
-  in: body
-  required: true
-  type: uuid
-
+    Filter results to only show tsigkeys that have an algorithm matching the filter
+  in: query
+  required: false
+  type: string
 
-description:
+tsigkey_name_filter:
   description: |
-    Description for the resource. Only showen in API / Horizon
-  in: body
-  required: true
+    Filter results to only show tsigkeys that have a name matching the filter
+  in: query
+  required: false
   type: string
 
-version:
+tsigkey_scope_filter:
   description: |
-    Version of the resource
-  in: body
-  required: true
-  type: integer
-
+    Filter results to only show tsigkeys that have a scope matching the filter
+  in: query
+  required: false
+  type: string
 
-created_at:
+zone_description_filter:
   description: |
-    Date / Time when resource was created
-  in: body
-  required: true
-  type: datestamp
+    Filter results to only show zones that have a description matching the filter
+  in: query
+  required: false
+  type: string
 
-updated_at:
+zone_email_filter:
   description: |
-    Date / Time when resource last updated
-  in: body
+    Filter results to only show zones that have an email matching the filter
+  in: query
   required: false
-  type: datestamp
+  type: string
 
-status:
+zone_export_message_filter:
   description: |
-    status of the resource
-  in: body
-  required: true
-  type: enum
+    Filter results to only show ``zone_exports`` that have a ``message`` matching the filter
+  in: query
+  required: false
+  type: string
 
-action:
+zone_export_status_filter:
   description: |
-    current action in progress on the resource
-  in: body
-  required: true
-  type: enum
+    Filter results to only show ``zone_exports`` that have a ``status`` matching the filter
+  in: query
+  required: false
+  type: string
 
-links:
+zone_export_zone_id_filter:
   description: |
-    Links to the resource, and other related resources.
-    When a response has been broken into pages, we will include
-    a ``next`` link that should be followed to retrive all results
-  in: body
-  required: true
-  type: object
+    Filter results to only show ``zone_exports`` that have a ``zone_id`` matching the filter
+  in: query
+  required: false
+  type: uuid
 
-metadata:
+zone_import_message_filter:
   description: |
-    Returns the ``total_count`` of resources matching this filter
-  in: body
-  required: true
-  type: object
-
-#############################
-#      Zone Variables       #
-#############################
-
-
-# Header Variables
-###################
-
-# Path Variables
-#################
-
-# Query Variables
-##################
-
-# Filters
-# 'name', 'type', 'email', 'status', 'description', 'ttl'
+    Filter results to only show zone_imports that have a ``message`` matching the filter
+  in: query
+  required: false
+  type: string
 
-zone_name_filter:
+zone_import_status_filter:
   description: |
-    Filter results to only show zones that have a name matching the filter
+    Filter results to only show zone_imports that have a ``status`` matching the filter
   in: query
   required: false
   type: string
 
-zone_type_filter:
+zone_import_zone_id_filter:
   description: |
-    Filter results to only show zones that have a type matching the filter
+    Filter results to only show zone_imports that have a ``zone_id`` matching the filter
   in: query
   required: false
-  type: string
+  type: uuid
 
-zone_email_filter:
+zone_name_filter:
   description: |
-    Filter results to only show zones that have an email matching the filter
+    Filter results to only show zones that have a name matching the filter
   in: query
   required: false
   type: string
@@ -226,9 +302,9 @@ zone_status_filter:
   required: false
   type: string
 
-zone_description_filter:
+zone_transfer_request_status_filter:
   description: |
-    Filter results to only show zones that have a description matching the filter
+    Filter results to only show ``zone_transfer_requests`` that have a ``status`` matching the filter
   in: query
   required: false
   type: string
@@ -240,167 +316,160 @@ zone_ttl_filter:
   required: false
   type: integer
 
-# Body Variables
-#################
+zone_type_filter:
+  description: |
+    Filter results to only show zones that have a type matching the filter
+  in: query
+  required: false
+  type: string
+
 
+####################
+#  Body Variables  #
+####################
 
-zone_name:
+action:
   description: |
-    DNS Name for the zone
+    current action in progress on the resource
   in: body
   required: true
-  type: domainname
+  type: enum
 
-zone_email:
+created_at:
   description: |
-    e-mail for the zone. Used in SOA records for the zone
+    Date / Time when resource was created
   in: body
   required: true
-  type: string
+  type: datestamp
 
-zone_email_update:
+description:
   description: |
-    e-mail for the zone. Used in SOA records for the zone
+    Description for the resource. Only showen in API / Horizon
   in: body
-  required: false
+  required: true
   type: string
 
-zone_ttl:
+id:
   description: |
-    TTL (Time to Live) for the zone.
+    ID for the resource
   in: body
-  required: false
-  type: integer
+  required: true
+  type: uuid
 
-zone_description:
+links:
   description: |
-    Description for this zone
+    Links to the resource, and other related resources.
+    When a response has been broken into pages, we will include
+    a ``next`` link that should be followed to retrive all results
   in: body
-  required: false
-  type: string
+  required: true
+  type: object
 
-zone_pool_id:
+max_page_limit:
   description: |
-    ID for the pool hosting this zone
+    The max amount of items allowed per page
   in: body
   required: true
-  type: uuid
+  type: integer
 
-zone_serial:
+max_recordset_name_length:
   description: |
-    current serial number for the zone
+    The max length of a recordset name
   in: body
   required: true
   type: integer
 
-zone_serial:
+max_recordset_records:
   description: |
-    current serial number for the zone
+    The max amount of records contained in a recordset
   in: body
   required: true
   type: integer
 
-zone_type:
+max_zone_name_length:
   description: |
-    Type of zone. PRIMARY is controlled by Designate, SECONDARY zones are slaved from another DNS Server. Defaults to PRIMARY
+    The max length of a zone name
   in: body
-  required: false
-  type: enum
+  required: true
+  type: integer
 
-zone_masters:
+max_zone_records:
   description: |
-    For secondary zones. The servers to slave from to get DNS information
+    The max amount of records in a zone
   in: body
   required: true
-  type: enum
+  type: integer
 
-zone_transfered_at:
+max_zone_recordsets:
   description: |
-    For secondary zones. The last time an update was retrieved from the master servers
+    The max amount of recordsets per zone
   in: body
   required: true
-  type: enum
+  type: integer
 
-zone_nameserver_hostname:
+max_zones:
   description: |
-    The hostname of the nameserver that the zone should be delegated to
+    The max amount of zones for this project
   in: body
   required: true
-  type: hostname
-
+  type: integer
 
-zone_nameserver_priority:
+metadata:
   description: |
-    The priority of the nameserver. This is used to determine the order of the
-    the nameserver listings, and which server is used in the SOA record for the
-    zone.
+    Returns the ``total_count`` of resources matching this filter
   in: body
   required: true
-  type: hostname
-
-
-#############################
-#    Recordset Variables    #
-#############################
-
-
-# Header Variables
-###################
-
-# Path Variables
-#################
-
-# Query Variables
-##################
-
-# Filters
-# 'name', 'type', 'ttl', 'data', 'status', 'description'
+  type: object
 
-recordset_name_filter:
+min_ttl:
   description: |
-    Filter results to only show recordsets that have a name matching the filter
-  in: query
-  required: false
-  type: string
+    The lowest ttl allowed on this system
+  in: body
+  required: true
+  type: integer
 
-recordset_type_filter:
+pool_attributes:
+  description: >
+    Key:Value pairs of information about this pool. This information can be used by the scheduler to place zones on the correct pools
+  in: body
+  required: true
+  type: object
+
+pool_id:
   description: |
-    Filter results to only show recordsets that have a type matching the filter
-  in: query
-  required: false
-  type: string
+    ID for this pool
+  in: body
+  required: true
+  type: uuid
 
-recordset_ttl_filter:
+pool_name:
   description: |
-    Filter results to only show recordsets that have a ttl matching the filter
-  in: query
-  required: false
+    Name for this pool
+  in: body
+  required: true
   type: string
 
-recordset_data_filter:
+pool_ns_records:
   description: |
-    Filter results to only show recordsets that have a record with data matching the filter
-  in: query
-  required: false
+    Name Servers for this pool. Any zones hosted by this pool should be delegated to these DNS servers
+  in: body
+  required: true
   type: string
 
-recordset_status_filter:
+project_id:
   description: |
-    Filter results to only show recordsets that have a status matching the filter
-  in: query
-  required: false
-  type: string
+    ID for the project that owns the resource
+  in: body
+  required: true
+  type: uuid
 
-recordset_description_filter:
+recordset_description:
   description: |
-    Filter results to only show recordsets that have a description matching the filter
-  in: query
+    Description for this recordset
+  in: body
   required: false
   type: string
 
-# Body Variables
-#################
-
 recordset_name:
   description: |
     DNS Name for the recordset
@@ -408,16 +477,11 @@ recordset_name:
   required: true
   type: hostname
 
-recordset_zone_id:
-  description: |
-    ID for the zone that contains this recordset
-  in: body
-  required: true
-  type: uuid
-
-recordset_zone_name:
+recordset_records:
   description: |
-    The name of the zone that contains this recordset
+    A list of data for this recordset. Each item will be a separate record in Designate
+    These items should conform to the DNS spec for the record type - e.g. A records
+    must be IPv4 addresses, CNAME records must be a hostname.
   in: body
   required: true
   type: string
@@ -436,186 +500,116 @@ recordset_type:
   required: true
   type: string
 
-recordset_records:
+recordset_zone_id:
   description: |
-    A list of data for this recordset. Each item will be a separate record in Designate
-    These items should conform to the DNS spec for the record type - e.g. A records
-    must be IPv4 addresses, CNAME records must be a hostname.
+    ID for the zone that contains this recordset
   in: body
   required: true
-  type: string
+  type: uuid
 
-recordset_description:
+recordset_zone_name:
   description: |
-    Description for this recordset
+    The name of the zone that contains this recordset
   in: body
-  required: false
-  type: string
-
-#############################
-#   Zone Import Variables   #
-#############################
-
-
-# Header Variables
-###################
-
-# Path Variables
-#################
-
-path_zone_import_id:
-  description: |
-    ID for this zone import
-  in: path
   required: true
-  type: uuid
-
-# Query Variables
-##################
-
-# Filters
-# 'status', 'message', 'zone_id'
-
-zone_import_zone_id_filter:
-  description: |
-    Filter results to only show zone_imports that have a ``zone_id`` matching the filter
-  in: query
-  required: false
-  type: uuid
-
-zone_import_status_filter:
-  description: |
-    Filter results to only show zone_imports that have a ``status`` matching the filter
-  in: query
-  required: false
   type: string
 
-zone_import_message_filter:
+resource_id:
   description: |
-    Filter results to only show zone_imports that have a ``message`` matching the filter
-  in: query
-  required: false
+    resource id for this tsigkey which can be either zone or pool id
+  in: body
+  required: true
   type: string
 
-
-
-# Body Variables
-#################
-
-zone_import_id:
+status:
   description: |
-    ID for this zone import
+    status of the resource
   in: body
   required: true
-  type: uuid
+  type: enum
 
-zone_import_zone_id:
+tld_description:
   description: |
-    ID for the zone that was created by this import
+    Description for this tld
   in: body
   required: false
-  type: uuid
+  type: string
 
-zone_import_status:
+tld_name:
   description: |
-    Current status of the zone import
+    Name for this tld
   in: body
   required: true
-  type: uuid
+  type: string
 
-zone_import_message:
+tsigkey_algorithm:
   description: |
-    Message about the current status of the import
+    The encryption algorithm for this tsigkey
   in: body
-  required: false
-  type: uuid
-
-#############################
-#   Zone Export Variables   #
-#############################
-
-
-# Header Variables
-###################
-
-zone_export_accepts:
-  description: >
-    Content-Type that will be accepted by the client.
-    This endpoint will send a response with a ``text/dns`` content-type.
-    If the client does not include a ``Accepts: text/dns`` header
-  in: header
   required: true
   type: string
 
-
-# Path Variables
-#################
-
-path_zone_export_id:
+tsigkey_name:
   description: |
-    ID for this zone export
-  in: path
+    Name for this tsigkey
+  in: body
   required: true
-  type: uuid
-
-# Query Variables
-##################
-
-# Filters
-# 'status', 'message', 'zone_id'
+  type: string
 
-zone_export_zone_id_filter:
+tsigkey_scope:
   description: |
-    Filter results to only show ``zone_exports`` that have a ``zone_id`` matching the filter
-  in: query
-  required: false
-  type: uuid
+    scope for this tsigkey which can be either ZONE or POOL scope
+  in: body
+  required: true
+  type: string
 
-zone_export_status_filter:
+tsigkey_secret:
   description: |
-    Filter results to only show ``zone_exports`` that have a ``status`` matching the filter
-  in: query
-  required: false
+    The actual key to be used
+  in: body
+  required: true
   type: string
 
-zone_export_message_filter:
+updated_at:
   description: |
-    Filter results to only show ``zone_exports`` that have a ``message`` matching the filter
-  in: query
+    Date / Time when resource last updated
+  in: body
   required: false
-  type: string
-
-
-
-# Body Variables
-#################
+  type: datestamp
 
-zone_export_id:
+version:
   description: |
-    ID for this zone export
+    Version of the resource
   in: body
   required: true
-  type: uuid
+  type: integer
 
-zone_export_zone_id:
+zone_description:
   description: |
-    ID for the zone that is being exported
+    Description for this zone
   in: body
   required: false
-  type: uuid
+  type: string
 
-zone_export_status:
+zone_email:
   description: |
-    Current status of the zone export
+    e-mail for the zone. Used in SOA records for the zone
   in: body
   required: true
   type: string
 
-zone_export_message:
+zone_email_update:
   description: |
-    Message about the current status of the export
+    e-mail for the zone. Used in SOA records for the zone
   in: body
   required: false
+  type: string
+
+zone_export_id:
+  description: |
+    ID for this zone export
+  in: body
+  required: true
   type: uuid
 
 zone_export_location:
@@ -638,380 +632,174 @@ zone_export_location:
   required: false
   type: string
 
-
-
-#################################
-#    Zone Transfer Variables    #
-#################################
-
-
-# Header Variables
-###################
-
-# Path Variables
-#################
-
-path_zone_transfer_request_id:
-  description: |
-    ID for this zone transfer request
-  in: path
-  required: true
-  type: uuid
-
-path_zone_transfer_accept_id:
-  description: |
-    ID for this zone transfer accept
-  in: path
-  required: true
-  type: uuid
-
-# Query Variables
-##################
-
-# Filters
-# 'status'
-
-zone_transfer_request_status_filter:
-  description: |
-    Filter results to only show ``zone_transfer_requests`` that have a ``status`` matching the filter
-  in: query
-  required: false
-  type: string
-
-# Body Variables
-#################
-zone_transfer_request_id:
-  description: |
-    ID for this zone transfer request
-  in: path
-  required: true
-  type: uuid
-
-zone_transfer_accept_id:
+zone_export_message:
   description: |
-    ID for this zone transfer accept
-  in: path
-  required: true
-  type: uuid
-
-zone_transfer_request_target_project_id:
-  description: >
-    A project ID that the request will be limited to.
-    No other project will be allowed to accept this request.
+    Message about the current status of the export
   in: body
   required: false
-  type: string
+  type: uuid
 
-zone_transfer_request_status:
+zone_export_status:
   description: |
-    Current status of the zone transfer request
+    Current status of the zone export
   in: body
   required: true
   type: string
 
-zone_transfer_accept_status:
+zone_export_zone_id:
   description: |
-    Current status of the zone transfer request
-  in: body
-  required: true
-  type: string
-
-zone_transfer_request_key:
-  description: >
-    Key that is used as part of the zone transfer accept process. This is only
-    shown to the creator, and must be communicated out of band.
+    ID for the zone that is being exported
   in: body
-  required: true
-  type: string
+  required: false
+  type: uuid
 
-zone_transfer_request_zone_id:
+zone_import_id:
   description: |
-    ID for the zone that is being exported
+    ID for this zone import
   in: body
   required: true
   type: uuid
 
-zone_transfer_request_zone_name:
+zone_import_message:
   description: |
-    the name of the zone that is being exported
+    Message about the current status of the import
   in: body
-  required: true
-  type: string
-
-
-#############################
-#     Limits Variables      #
-#############################
-
-
-# Header Variables
-###################
-
-# Path Variables
-#################
-
-# Query Variables
-##################
-
-# Body Variables
-#################
+  required: false
+  type: uuid
 
-max_page_limit:
+zone_import_status:
   description: |
-    The max amount of items allowed per page
+    Current status of the zone import
   in: body
   required: true
-  type: integer
+  type: uuid
 
-max_recordset_name_length:
+zone_import_zone_id:
   description: |
-    The max length of a recordset name
+    ID for the zone that was created by this import
   in: body
-  required: true
-  type: integer
+  required: false
+  type: uuid
 
-max_recordset_records:
+zone_masters:
   description: |
-    The max amount of records contained in a recordset
+    For secondary zones. The servers to slave from to get DNS information
   in: body
   required: true
-  type: integer
+  type: enum
 
-max_zone_name_length:
+zone_name:
   description: |
-    The max length of a zone name
+    DNS Name for the zone
   in: body
   required: true
-  type: integer
+  type: domainname
 
-max_zone_records:
+zone_nameserver_hostname:
   description: |
-    The max amount of records in a zone
+    The hostname of the nameserver that the zone should be delegated to
   in: body
   required: true
-  type: integer
+  type: hostname
 
-max_zone_recordsets:
+zone_nameserver_priority:
   description: |
-    The max amount of recordsets per zone
+    The priority of the nameserver. This is used to determine the order of the
+    the nameserver listings, and which server is used in the SOA record for the
+    zone.
   in: body
   required: true
   type: integer
 
-max_zones:
+zone_pool_id:
   description: |
-    The max amount of zones for this project
+    ID for the pool hosting this zone
   in: body
   required: true
-  type: integer
+  type: uuid
 
-min_ttl:
+zone_serial:
   description: |
-    The lowest ttl allowed on this system
+    current serial number for the zone
   in: body
   required: true
   type: integer
 
-
-#############################
-#      Pool Variables       #
-#############################
-
-
-# Header Variables
-###################
-
-# Path Variables
-#################
-
-path_pool_id:
-  description: |
-    ID for this pool
-  in: path
-  required: true
-  type: uuid
-
-# Query Variables
-##################
-
-# Body Variables
-#################
-pool_id:
+zone_transfer_accept_id:
   description: |
-    ID for this pool
-  in: path
+    ID for this zone transfer accept
+  in: body
   required: true
   type: uuid
 
-pool_name:
-  description: |
-    Name for this pool
-  in: path
-  required: true
-  type: string
-
-pool_ns_records:
+zone_transfer_accept_status:
   description: |
-    Name Servers for this pool. Any zones hosted by this pool should be delegated to these DNS servers
-  in: path
+    Current status of the zone transfer request
+  in: body
   required: true
   type: string
 
-pool_attributes:
-  description: >
-    Key:Value pairs of information about this pool. This information can be used by the scheduler to place zones on the correct pools
-  in: path
-  required: true
-  type: object
-
-
-#############################
-#      Tld Variables       #
-#############################
-
-
-# Header Variables
-###################
-
-# Path Variables
-#################
-
-tld_id:
+zone_transfer_request_id:
   description: |
-    ID for this tld
-  in: path
+    ID for this zone transfer request
+  in: body
   required: true
   type: uuid
 
-# Query Variables
-##################
-
-# Filters
-
-tld_name_filter:
-  description: |
-    Filter results to only show tlds that have a name matching the filter
-  in: query
-  required: false
-  type: string
-
-
-# Body Variables
-#################
-
-tld_name:
-  description: |
-    Name for this tld
+zone_transfer_request_key:
+  description: >
+    Key that is used as part of the zone transfer accept process. This is only
+    shown to the creator, and must be communicated out of band.
   in: body
   required: true
   type: string
 
-tld_description:
+zone_transfer_request_status:
   description: |
-    Description for this tld
+    Current status of the zone transfer request
   in: body
-  required: false
-  type: string
-
-
-#############################
-#      Tsigkey Variables       #
-#############################
-
-
-# Header Variables
-###################
-
-# Path Variables
-#################
-
-tsigkey_id:
-  description: |
-    ID for this tsigkey
-  in: path
   required: true
-  type: uuid
-
-
-# Query Variables
-##################
-
-#Filters
-
-tsigkey_name_filter:
-  description: |
-    Filter results to only show tsigkeys that have a name matching the filter
-  in: query
-  required: false
   type: string
 
-tsigkey_algorithm_filter:
-  description: |
-    Filter results to only show tsigkeys that have an algorithm matching the filter
-  in: query
-  required: false
-  type: string
-
-tsigkey_scope_filter:
-  description: |
-    Filter results to only show tsigkeys that have a scope matching the filter
-  in: query
+zone_transfer_request_target_project_id:
+  description: >
+    A project ID that the request will be limited to.
+    No other project will be allowed to accept this request.
+  in: body
   required: false
   type: string
 
-
-# Body Variables
-#################
-
-tsigkey_name:
+zone_transfer_request_zone_id:
   description: |
-    Name for this tsigkey
+    ID for the zone that is being exported
   in: body
   required: true
-  type: string
+  type: uuid
 
-tsigkey_algorithm:
+zone_transfer_request_zone_name:
   description: |
-    The encryption algorithm for this tsigkey
+    the name of the zone that is being exported
   in: body
   required: true
   type: string
 
-tsigkey_secret:
+zone_transfered_at:
   description: |
-    The actual key to be used
+    For secondary zones. The last time an update was retrieved from the master servers
   in: body
   required: true
-  type: string
+  type: enum
 
-tsigkey_scope:
+zone_ttl:
   description: |
-    scope for this tsigkey which can be either ZONE or POOL scope
+    TTL (Time to Live) for the zone.
   in: body
-  required: true
-  type: string
+  required: false
+  type: integer
 
-resource_id:
+zone_type:
   description: |
-    resource id for this tsigkey which can be either zone or pool id
+    Type of zone. PRIMARY is controlled by Designate, SECONDARY zones are slaved from another DNS Server. Defaults to PRIMARY
   in: body
-  required: true
-  type: string
-
-
-#############################
-#      <ITEM> Variables       #
-#############################
-
-
-# Header Variables
-###################
-
-# Path Variables
-#################
-
-# Query Variables
-##################
-
-# Body Variables
-#################
+  required: false
+  type: enum
diff --git a/api-ref/source/params.yaml b/api-ref/source/params.yaml
new file mode 100644
index 00000000..c5fb98f2
--- /dev/null
+++ b/api-ref/source/params.yaml
@@ -0,0 +1,806 @@
+####################
+# Header Variables #
+####################
+
+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-auth-token:
+  description: |
+    Token used to identify the user from keystone
+  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
+
+zone_export_accepts:
+  description: >
+    Content-Type that will be accepted by the client.
+    This endpoint will send a response with a ``text/dns`` content-type.
+    If the client does not include a ``Accepts: text/dns`` header
+  in: header
+  required: true
+  type: string
+
+####################
+#  Path Variables  #
+####################
+
+path_pool_id:
+  description: |
+    ID for this pool
+  in: path
+  required: true
+  type: uuid
+
+path_recordset_id:
+  description: |
+    ID for the recordset
+  in: path
+  required: true
+  type: uuid
+
+path_zone_id:
+  description: |
+    ID for the zone
+  in: path
+  required: true
+  type: uuid
+
+path_zone_export_id:
+  description: |
+    ID for this zone export
+  in: path
+  required: true
+  type: uuid
+
+path_zone_import_id:
+  description: |
+    ID for this zone import
+  in: path
+  required: true
+  type: uuid
+
+path_zone_transfer_accept_id:
+  description: |
+    ID for this zone transfer accept
+  in: path
+  required: true
+  type: uuid
+
+path_zone_transfer_request_id:
+  description: |
+    ID for this zone transfer request
+  in: path
+  required: true
+  type: uuid
+
+tld_id:
+  description: |
+    ID for this tld
+  in: path
+  required: true
+  type: uuid
+
+tsigkey_id:
+  description: |
+    ID for this tsigkey
+  in: path
+  required: true
+  type: uuid
+
+####################
+# 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
+
+recordset_data_filter:
+  description: |
+    Filter results to only show recordsets that have a record with data matching the filter
+  in: query
+  required: false
+  type: string
+
+recordset_description_filter:
+  description: |
+    Filter results to only show recordsets that have a description matching the filter
+  in: query
+  required: false
+  type: string
+
+recordset_name_filter:
+  description: |
+    Filter results to only show recordsets that have a name matching the filter
+  in: query
+  required: false
+  type: string
+
+recordset_status_filter:
+  description: |
+    Filter results to only show recordsets that have a status matching the filter
+  in: query
+  required: false
+  type: string
+
+recordset_ttl_filter:
+  description: |
+    Filter results to only show recordsets that have a ttl matching the filter
+  in: query
+  required: false
+  type: string
+
+recordset_type_filter:
+  description: |
+    Filter results to only show recordsets that have a type matching the filter
+  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
+
+tld_name_filter:
+  description: |
+    Filter results to only show tlds that have a name matching the filter
+  in: query
+  required: false
+  type: string
+
+tsigkey_algorithm_filter:
+  description: |
+    Filter results to only show tsigkeys that have an algorithm matching the filter
+  in: query
+  required: false
+  type: string
+
+tsigkey_name_filter:
+  description: |
+    Filter results to only show tsigkeys that have a name matching the filter
+  in: query
+  required: false
+  type: string
+
+tsigkey_scope_filter:
+  description: |
+    Filter results to only show tsigkeys that have a scope matching the filter
+  in: query
+  required: false
+  type: string
+
+zone_description_filter:
+  description: |
+    Filter results to only show zones that have a description matching the filter
+  in: query
+  required: false
+  type: string
+
+zone_email_filter:
+  description: |
+    Filter results to only show zones that have an email matching the filter
+  in: query
+  required: false
+  type: string
+
+zone_export_message_filter:
+  description: |
+    Filter results to only show ``zone_exports`` that have a ``message`` matching the filter
+  in: query
+  required: false
+  type: string
+
+zone_export_status_filter:
+  description: |
+    Filter results to only show ``zone_exports`` that have a ``status`` matching the filter
+  in: query
+  required: false
+  type: string
+
+zone_export_zone_id_filter:
+  description: |
+    Filter results to only show ``zone_exports`` that have a ``zone_id`` matching the filter
+  in: query
+  required: false
+  type: uuid
+
+zone_import_message_filter:
+  description: |
+    Filter results to only show zone_imports that have a ``message`` matching the filter
+  in: query
+  required: false
+  type: string
+
+zone_import_status_filter:
+  description: |
+    Filter results to only show zone_imports that have a ``status`` matching the filter
+  in: query
+  required: false
+  type: string
+
+zone_import_zone_id_filter:
+  description: |
+    Filter results to only show zone_imports that have a ``zone_id`` matching the filter
+  in: query
+  required: false
+  type: uuid
+
+zone_name_filter:
+  description: |
+    Filter results to only show zones that have a name matching the filter
+  in: query
+  required: false
+  type: string
+
+zone_status_filter:
+  description: |
+    Filter results to only show zones that have a status matching the filter
+  in: query
+  required: false
+  type: string
+
+zone_transfer_request_status_filter:
+  description: |
+    Filter results to only show ``zone_transfer_requests`` that have a ``status`` matching the filter
+  in: query
+  required: false
+  type: string
+
+zone_ttl_filter:
+  description: |
+    Filter results to only show zones that have a ttl matching the filter
+  in: query
+  required: false
+  type: integer
+
+zone_type_filter:
+  description: |
+    Filter results to only show zones that have a type matching the filter
+  in: query
+  required: false
+  type: string
+
+
+####################
+#  Body Variables  #
+####################
+
+action:
+  description: |
+    current action in progress on the resource
+  in: body
+  required: true
+  type: enum
+
+created_at:
+  description: |
+    Date / Time when resource was created
+  in: body
+  required: true
+  type: datestamp
+
+description:
+  description: |
+    Description for the resource. Only showen in API / Horizon
+  in: body
+  required: true
+  type: string
+
+id:
+  description: |
+    ID for the resource
+  in: body
+  required: true
+  type: uuid
+
+links:
+  description: |
+    Links to the resource, and other related resources.
+    When a response has been broken into pages, we will include
+    a ``next`` link that should be followed to retrive all results
+  in: body
+  required: true
+  type: object
+
+max_page_limit:
+  description: |
+    The max amount of items allowed per page
+  in: body
+  required: true
+  type: integer
+
+max_recordset_name_length:
+  description: |
+    The max length of a recordset name
+  in: body
+  required: true
+  type: integer
+
+max_recordset_records:
+  description: |
+    The max amount of records contained in a recordset
+  in: body
+  required: true
+  type: integer
+
+max_zone_name_length:
+  description: |
+    The max length of a zone name
+  in: body
+  required: true
+  type: integer
+
+max_zone_records:
+  description: |
+    The max amount of records in a zone
+  in: body
+  required: true
+  type: integer
+
+max_zone_recordsets:
+  description: |
+    The max amount of recordsets per zone
+  in: body
+  required: true
+  type: integer
+
+max_zones:
+  description: |
+    The max amount of zones for this project
+  in: body
+  required: true
+  type: integer
+
+metadata:
+  description: |
+    Returns the ``total_count`` of resources matching this filter
+  in: body
+  required: true
+  type: object
+
+min_ttl:
+  description: |
+    The lowest ttl allowed on this system
+  in: body
+  required: true
+  type: integer
+
+project_id:
+  description: |
+    ID for the project that owns the resource
+  in: body
+  required: true
+  type: uuid
+
+pool_attributes:
+  description: >
+    Key:Value pairs of information about this pool. This information can be used by the scheduler to place zones on the correct pools
+  in: path
+  required: true
+  type: object
+
+pool_id:
+  description: |
+    ID for this pool
+  in: path
+  required: true
+  type: uuid
+
+pool_name:
+  description: |
+    Name for this pool
+  in: path
+  required: true
+  type: string
+
+pool_ns_records:
+  description: |
+    Name Servers for this pool. Any zones hosted by this pool should be delegated to these DNS servers
+  in: path
+  required: true
+  type: string
+
+
+recordset_description:
+  description: |
+    Description for this recordset
+  in: body
+  required: false
+  type: string
+
+recordset_name:
+  description: |
+    DNS Name for the recordset
+  in: body
+  required: true
+  type: hostname
+
+recordset_ttl:
+  description: |
+    TTL (Time to Live) for the recordset.
+  in: body
+  required: false
+  type: integer
+
+recordset_type:
+  description: |
+    They RRTYPE of the recordset.
+  in: body
+  required: true
+  type: string
+
+recordset_records:
+  description: |
+    A list of data for this recordset. Each item will be a separate record in Designate
+    These items should conform to the DNS spec for the record type - e.g. A records
+    must be IPv4 addresses, CNAME records must be a hostname.
+  in: body
+  required: true
+  type: string
+
+recordset_zone_id:
+  description: |
+    ID for the zone that contains this recordset
+  in: body
+  required: true
+  type: uuid
+
+recordset_zone_name:
+  description: |
+    The name of the zone that contains this recordset
+  in: body
+  required: true
+  type: string
+
+resource_id:
+  description: |
+    resource id for this tsigkey which can be either zone or pool id
+  in: body
+  required: true
+  type: string
+
+status:
+  description: |
+    status of the resource
+  in: body
+  required: true
+  type: enum
+
+tsigkey_algorithm:
+  description: |
+    The encryption algorithm for this tsigkey
+  in: body
+  required: true
+  type: string
+
+tld_description:
+  description: |
+    Description for this tld
+  in: body
+  required: false
+  type: string
+
+tld_name:
+  description: |
+    Name for this tld
+  in: body
+  required: true
+  type: string
+
+tsigkey_name:
+  description: |
+    Name for this tsigkey
+  in: body
+  required: true
+  type: string
+
+tsigkey_scope:
+  description: |
+    scope for this tsigkey which can be either ZONE or POOL scope
+  in: body
+  required: true
+  type: string
+
+tsigkey_secret:
+  description: |
+    The actual key to be used
+  in: body
+  required: true
+  type: string
+
+updated_at:
+  description: |
+    Date / Time when resource last updated
+  in: body
+  required: false
+  type: datestamp
+
+version:
+  description: |
+    Version of the resource
+  in: body
+  required: true
+  type: integer
+
+zone_description:
+  description: |
+    Description for this zone
+  in: body
+  required: false
+  type: string
+
+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_export_id:
+  description: |
+    ID for this zone export
+  in: body
+  required: true
+  type: uuid
+
+zone_export_location:
+  description: >
+    Where the exported zone is published to.
+    There are currently one placement option available - designate.
+
+    This will be shown by ``designate://<url>``.
+
+    As more drivers are added, this will expand to include swift - this will be
+    indicated by location being set to ``swift://<region>/<container>/<file>``
+
+    This is also allowed be a webserver if the operator implements a different
+    data store, and will be indicted by ``http://<url>``
+
+    When a zone export is complete, the location will be updated, and
+    the exported zone file will be available at the location specified.
+
+  in: body
+  required: false
+  type: string
+
+zone_export_message:
+  description: |
+    Message about the current status of the export
+  in: body
+  required: false
+  type: uuid
+
+zone_export_status:
+  description: |
+    Current status of the zone export
+  in: body
+  required: true
+  type: string
+
+zone_export_zone_id:
+  description: |
+    ID for the zone that is being exported
+  in: body
+  required: false
+  type: uuid
+
+zone_import_id:
+  description: |
+    ID for this zone import
+  in: body
+  required: true
+  type: uuid
+
+zone_import_message:
+  description: |
+    Message about the current status of the import
+  in: body
+  required: false
+  type: uuid
+
+zone_import_status:
+  description: |
+    Current status of the zone import
+  in: body
+  required: true
+  type: uuid
+
+zone_import_zone_id:
+  description: |
+    ID for the zone that was created by this import
+  in: body
+  required: false
+  type: uuid
+
+zone_masters:
+  description: |
+    For secondary zones. The servers to slave from to get DNS information
+  in: body
+  required: true
+  type: enum
+
+zone_nameserver_hostname:
+  description: |
+    The hostname of the nameserver that the zone should be delegated to
+  in: body
+  required: true
+  type: hostname
+
+zone_nameserver_priority:
+  description: |
+    The priority of the nameserver. This is used to determine the order of the
+    the nameserver listings, and which server is used in the SOA record for the
+    zone.
+  in: body
+  required: true
+  type: integer
+
+zone_name:
+  description: |
+    DNS Name for the zone
+  in: body
+  required: true
+  type: domainname
+
+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_transfered_at:
+  description: |
+    For secondary zones. The last time an update was retrieved from the master servers
+  in: body
+  required: true
+  type: enum
+
+zone_transfer_accept_id:
+  description: |
+    ID for this zone transfer accept
+  in: path
+  required: true
+  type: uuid
+
+zone_transfer_accept_status:
+  description: |
+    Current status of the zone transfer request
+  in: body
+  required: true
+  type: string
+
+zone_transfer_request_id:
+  description: |
+    ID for this zone transfer request
+  in: path
+  required: true
+  type: uuid
+
+zone_transfer_request_target_project_id:
+  description: >
+    A project ID that the request will be limited to.
+    No other project will be allowed to accept this request.
+  in: body
+  required: false
+  type: string
+
+zone_transfer_request_status:
+  description: |
+    Current status of the zone transfer request
+  in: body
+  required: true
+  type: string
+
+zone_transfer_request_key:
+  description: >
+    Key that is used as part of the zone transfer accept process. This is only
+    shown to the creator, and must be communicated out of band.
+  in: body
+  required: true
+  type: string
+
+zone_transfer_request_zone_id:
+  description: |
+    ID for the zone that is being exported
+  in: body
+  required: true
+  type: uuid
+
+zone_transfer_request_zone_name:
+  description: |
+    the name of the zone that is being exported
+  in: body
+  required: true
+  type: string
+
+zone_ttl:
+  description: |
+    TTL (Time to Live) for the zone.
+  in: body
+  required: false
+  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