Documenting Rails API-POST-Aktion mit Parametern in Körper

Question

Ich benutze Ruby on Rails, um eine Rest-API für einen Client zu architect und versuchen, es mithilfe von SwaggerHub zu dokumentieren.

Ich würde gerne wissen, wie man eine Post-Aktion mit den richtigen Parametern im BODY dokumentiert. Bisher habe ich die Aktion erstellt und muss die folgenden Parameter für meine Entwickler beschreiben.

"post": { 
    "description": "Creates a user", 
    "produces": [ 
    "application/json" 
    ], 
    "consumes": [ 
    "application/json" 
    ], 
    "responses": { 
    "201": { 
     "description": "Creates an instance of User", 
    }, 
    "422": { 
     "description": "Bad syntax, user not created" 
    } 
    } 
} 

Es ist einfach, mit den Parametern "in PATH zu dokumentieren, wie die Get oder löschen Aktion, die den Benutzer-ID in dem params hat wie:

{"user": {"email":"999999@gmail.com", "password":"12345678", "password_confirmation":"12345678"}} 

Ich habe mit diesem für meinen Beitrag Aktion begann diese

"delete": { 
    "description": "Destroy a user", 
    "produces": [ 
    "application/json" 
    ], 
    "consumes": [ 
    "application/json" 
    ], 
    "responses": { 
    "200": { 
     "description": "destory a single user", 
    }, 
    "404": { 
     "description": "user not found" 
    } 
    } 
}, 
    "parameters": [ 
    { 
    "name": "id", 
    "in": "path", 
    "description": "ID of user to use for action", 
    "required": true, 
    "type": "array", 
    "items": { 
     "type": "integer" 
    } 

Wie kann ich dokumentieren die Parameter mit params "in": "Körper"

Answer 1

Sie Sie müssen lediglich eine Parameterliste innerhalb des Posts hinzufügen und einen Parameter mit dem Eintrag in body hinzufügen.

swagger: "2.0" 

info: 
    version: 1.0.0 
    title: Simple API 
    description: A parameter body example 

paths: 
    /users: 
    post: 
     description: creates a user 
     produces: 
     - application/json 
     consumes: 
     - application/json 
     parameters: 
     - name: user 
      in: body 
      schema: 
      properties: 
       user: 
       properties: 
        email: 
        type: string 
        password: 
        type: string 
        password_confirmation: 
        type: string 
     responses: 
     201: 
      description: Creates an instance of User 
     422: 
      description: Bad syntax, user not created 

Sie können durch das Lesen the specification description und this tutorial viele Informationen über die OpenAPI (. Fka Swagger) Spezifikation finden (Offenlegung: Ich habe es geschrieben).