api-ref: verify keypairs

This verifies all the parts of keypairs, including filling out all the
details for microversion 2.2 and 2.10 which change it.

Part of bp:api-ref-in-rst

Change-Id: Iab88dc75cdb7b5f91e46afd29ee61e38b325e180

api-ref/source/os-keypairs.inc

@@ -1,7 +1,4 @@
 .. -*- rst -*-
-.. needs:parameter_verification
-.. needs:example_verification
-.. needs:body_verification
 
 =====================
  Keypairs (keypairs)
@@ -23,6 +20,15 @@ Error response codes: unauthorized(401), forbidden(403)
 Response
 --------
 
+.. rest_parameters:: parameters.yaml
+
+  - keypairs: keypairs
+  - name: keypair_name
+  - public_key: keypair_public_key
+  - fingerprint: keypair_fingerprint
+  - type: keypair_type
+  - user_id: keypair_userid
+
 **Example List Keypairs: JSON response**
 
 .. literalinclude:: ../../doc/api_samples/keypairs/keypairs-list-resp.json
@@ -35,7 +41,11 @@ Create Or Import Keypair
 
 Generates or imports a keypair.
 
-Normal response codes: 200
+Normal response codes: 200, 201
+
+.. note::
+
+   The success status code was changed from 200 to 201 in version 2.2
 
 Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)
 
@@ -44,8 +54,11 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-  - name: name
+  - keypair: keypair
-  - public_key: public_key
+  - name: keypair_name
+  - public_key: keypair_public_key_in
+  - type: keypair_type_in
+  - user_id: keypair_userid_in
 
 **Example Create Or Import Keypair: JSON request**
 
@@ -55,6 +68,16 @@ Request
 Response
 --------
 
+.. rest_parameters:: parameters.yaml
+
+  - keypair: keypair
+  - name: keypair_name
+  - public_key: keypair_public_key
+  - private_key: keypair_private_key
+  - fingerprint: keypair_fingerprint
+  - type: keypair_type
+  - user_id: keypair_userid
+
 **Example Create Or Import Keypair: JSON response**
 
 .. literalinclude:: ../../doc/api_samples/keypairs/keypairs-import-post-resp.json
@@ -76,11 +99,21 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-  - keypair_name: keypair_name
+  - keypair_name: keypair_name_path
+  - user_id: keypair_userid_in
 
 Response
 --------
 
+.. rest_parameters:: parameters.yaml
+
+  - keypair: keypair
+  - name: keypair_name
+  - public_key: keypair_public_key
+  - fingerprint: keypair_fingerprint
+  - type: keypair_type
+  - user_id: keypair_userid
+
 **Example Show Keypair Details: JSON response**
 
 .. literalinclude:: ../../doc/api_samples/keypairs/keypairs-get-resp.json
@@ -93,7 +126,12 @@ Delete Keypair
 
 Deletes a keypair.
 
-Normal response codes: 202
+Normal response codes: 202, 204
+
+.. note::
+
+   The normal return code is 204 in version 2.2 to match the fact that
+   no body content is returned.
 
 Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
 
@@ -103,6 +141,9 @@ Request
 .. rest_parameters:: parameters.yaml
 
   - keypair_name: keypair_name
+  - user_id: keypair_userid_in
 
 Response
 --------
+
+There is no body returned in a successful response.

api-ref/source/parameters.yaml

@@ -154,7 +154,7 @@ key:
   in: path
   required: true
   type: string
-keypair_name:
+keypair_name_path:
   description: |
     The keypair name.
   in: path
@@ -414,6 +414,13 @@ ip_query:
   in: query
   required: false
   type: string
+keypair_type_in:
+  in: query
+  required: false
+  type: string
+  description: |
+    The type of the keypair. Allowed values are ``ssh`` or ``x509``
+  min_version: 2.2
 limit:
   description: |
     Requests a page size of items. Returns a number of items up to a limit value.
@@ -1831,6 +1838,74 @@ key_pairs_quota_optional:
   in: body
   required: false
   type: integer
+keypair:
+  in: body
+  type: object
+  required: true
+  description: |
+    Keypair object
+keypair_fingerprint:
+  in: body
+  required: true
+  type: string
+  description: |
+    The fingerprint for the keypair.
+keypair_name:
+  in: body
+  required: true
+  type: string
+  description: |
+    A name for the keypair which will be used to reference it later.
+keypair_private_key:
+  description: |
+    If you do not provide a public key on create, a new keypair will
+    be built for you, and the private key will be returned during the
+    initial create call. Make sure to save this, as there is no way to
+    get this private key again in the future.
+  in: body
+  required: false
+  type: string
+keypair_public_key:
+  description: |
+    The keypair public key.
+  in: body
+  required: true
+  type: string
+keypair_public_key_in:
+  description: |
+    The public ssh key to import. If you omit this value, a keypair is
+    generated for you.
+  in: body
+  required: false
+  type: string
+keypair_type:
+  in: body
+  required: true
+  type: string
+  description: |
+    The type of the keypair. Allowed values are ``ssh`` or ``x509``
+  min_version: 2.2
+keypair_userid:
+  in: body
+  required: true
+  type: string
+  description: |
+    The user_id for a keypair.
+  min_version: 2.10
+keypair_userid_in:
+  in: body
+  required: false
+  type: string
+  description: |
+    The user_id for a keypair. This allows administrative users to
+    upload keys for other users than themselves.
+  min_version: 2.10
+keypairs:
+  in: body
+  type: array
+  required: true
+  description: |
+    Array of Keypair objects
 length:
   description: |
     The number of lines to fetch from the end of console log. All
@@ -2395,12 +2470,6 @@ project_id_server_group:
   in: body
   required: false
   type: string
-public_key:
-  description: |
-    The public ssh key to import. If you omit this value, a key is generated.
-  in: body
-  required: false
-  type: string
 quota_set:
   description: |
     A ``quota_set`` object.