Apiary: Is it possible to document what JSON response fields are?

前端 未结 2 1348
名媛妹妹
名媛妹妹 2021-02-14 20:12

I would like to document what the actual JSON fields themselves represent.

I have documented the GET statement, and parameters but this does not make a complete document

相关标签:
2条回答
  • 2021-02-14 20:44

    I don't think it is supported yet.

    I solved this problem in my project by putting a table with the description right above the GET request line. In your case it could look like:

    ### List all Applications 
    
    | Field                            | Description               |
    |----------------------------------|---------------------------|
    | Catalog.Applications.OtherFields | Documentation goes here.. |
    
    ### Get List of Applications [GET]
    

    To help you create the table in Markdown syntax you can use Markdown Tables generator.

    Note that the table generator lets you save the table definition to a file so next time you would need to edit the table you can start from where you left off .

    0 讨论(0)
  • 2021-02-14 20:50

    Update: We have just rolled out a beta of attributes description using the MSON syntax.

    The original payload could be then described as

    ### 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": ""
                        }]
                    }
                }
    

    Note the explicit JSON in body is redundant and you can skip it completely. See API Blueprint specification – Attributes for additional details

    0 讨论(0)
提交回复
热议问题