Copia: ¿Es posible documentar lo que son los campos de respuesta JSON?

Question

Me gustaría documentar lo que representan los campos JSON reales.

He documentado la Declaración de Obtención, y los parámetros, pero esto no hace una documentación completa para dar a los usuarios.

Entonces, en el ejemplo a continuación, ¿cómo agregaría un comentario sobre "OtrosFields"?¿Se apoya esto?O necesito hacer un documento de compañero en otro lugar.

## View Applications [/cat{?sort}{&order}{&page}]
### List all Applications 
### Get List of Applications [GET]
+ Parameters
    + sort (optional, string) ... `sort` parameter is used to specify which criteria to use for sorting. One of the following strings may be used: 
    `"NAME", 
    "RATING", "QUALITY" ,
    "RISKLEVEL", `

    + order (optional, string) ... `order` parameter is used to specify which order to use if sorting is used. One of the following strings may be used: 
    `"ASC", 
    "DESC"`

    + page (optional, int ) ... `page` parameter is used to request subsequent catalog pages.


+ Response 200 (application/json)

                {
            "Catalog" : {
                "Page" : 0,
                "Count" : 6,
                "Applications" : [{
                        "UID" : "6882e96a-5da1-11e3-1111-3f24f45df3ad"
                        "OtherFields: ""
               }]
               }}

Answer 1

Actualización: Acabamos de desplegar una beta de atributos de la descripción usando la Mson Syntax .

La carga útil original podría luego describirse como

### Get List of Applications [GET]

+ Response 200 (application/json)

    + Attributes
        + Catalog (object)
            + Page: 0 (number) - Number of the page
            + Count: 6 (number) - Count of *Lorem Ipsum*
            + Applications (array) - Some array of something
                + (object)
                    + UID: `6882e96a-5da1-11e3-1111-3f24f45df3ad`
                    + OtherFields

    + Body 

            {
                "Catalog" : {
                    "Page" : 0,
                    "Count" : 6,
                    "Applications" : [{
                        "UID" : "6882e96a-5da1-11e3-1111-3f24f45df3ad"
                        "OtherFields": ""
                    }]
                }
            }

NOTA El JSON explícito en el cuerpo es redundante y puede omitirlo completamente.Ver la especificación de API Blueprint - atributos para detalles adicionales

Answer 2

No creo que se apoye todavía.

Resolví este problema en mi proyecto al poner una tabla con la descripción justo por encima de la línea de solicitud de obtención.En su caso podría parecer:

### List all Applications 

| Field                            | Description               |
|----------------------------------|---------------------------|
| Catalog.Applications.OtherFields | Documentation goes here.. |

### Get List of Applications [GET]

Para ayudarlo a crear la tabla en la sintaxis de Markdown, puede usarla Generador de tablas de Markdown .

Tenga en cuenta que el generador de tabla le permite guardar la definición de la tabla a un archivo de la siguiente manera que necesite para editar la tabla que puede comenzar desde donde lo dejó.