问题
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 documentation to give to users.
So, in the example below how would I add a comment about "OtherFields". Is this supported? Or do I need to make a companion document somewhere else.
## 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: ""
}]
}}
回答1:
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
回答2:
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 .
来源:https://stackoverflow.com/questions/21043514/apiary-is-it-possible-to-document-what-json-response-fields-are