apiblueprint结构来实现所需的描述

Question

我目前有这样一个API蓝图，但是我无法实现正确的渲染。

    FORMAT: 1A
    HOST: http://polls.apiblueprint.org/

    #  Samwise Web API

    This document describes Samwise system WebAPI. Developers should refer to [this reference](https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf)  for
    the guidelines about how to design good API. Please maintain good and coherent writing style.


    # Group Sample API  

    This section describes sample-related operations.    

    ## Project Sample Retrieval [/projects/{projectId}/samples/{?sampleId}]  

    + Parameters

        + projectId (int, `1`) ... Project ID
        + sampleId (optional, int, `124357891`) ... Sample ID to return full information



    ### Get samples [GET]

    Returns specified sampleId if it belongs to given project. If no sampleId is specified, return all samples of given project.


    + Response 200 (application/json)
        + Attributes (SampleDTO)

    + Response 404 (application/json)
        Sample in request does not exist in current project, or if no SampleId is specified -  project does not have samples.


    ### Create arbitrary set of samples inside given project [POST]

    This method facilitates the scenario, when a random set of samples is created, each sample can belong to arbitrary subject or created without subject attached. 
    The entities must belong to one project.


    ### Create set of samples for many subjects inside given project [POST]

    This method facilitates the scenario, when a fixed set of samples is created for number of subjects, so every subject receives same set of samples. Subjects are created 
    if not found. If no subject is given, samples set is created without attachment to any subject. The entities must belong to one project.


    # Data Structures


    ## SamplePropertiesDTO (object)
    + ExternalSampleId: 12A4  (string, optional) - External Sample Id, such as parallel barcode from different system
    + ExternalSubjectId: 21az (string,optional) - External Subject Id, such as parallel identifier from different system
    + NumberOfVisits: 1 (number, optional) - Number Of Visits (?)
    + TimePointUnitId (number, 1) -  Identifier of unit used in Time Point  
    + SampleAmountUnitId (number, 1) - Sample Amount Unit Id, int (This relates to a table that contains all the sample units (volume,mass,concentration...))
    + SampleAmount (number, 0.001) - Sample amount
    + Aliquote (optional, string, 'A123') - aliquote string
    + SampleTypeId (required, number) - Sample Type identifier


    ## SampleDTO (object)
    + SampleId (number,123456789, required)  - Sample ID
    + SampleProperties(SamplePropertiesDTO)
    + ClientSampleId (number, 1, optional) - Identifier of Sample ID received from client in request
    + Events (array[SamplePropertiesDTO], required) - Collection of sample events

我的问题是：

主要是我想要 tables 用于请求和响应有效负载。我想实现布局："Response" -> table，其中 json 对象的字段作为有效负载响应。如果我放置“+ Attributes”（参见我的蓝图），我设法让它显示出来，但我不确定当您将 json 对象作为有效负载时，这是描述情况的正确方法。也许应该使用其他关键字？
当 table 使用描述为“+ SampleProperties(SamplePropertiesDTO)”的字段呈现时，它在呈现页面中显示为 table 中的一行，SampleProperties 为类型对象，SamplePropertiesDTO 的内容在呈现的页面上无处可寻。然而，我将它内联或作为文档的单独部分存在，例如所有数据结构所在的位置。
如果可能，我想单独显式显示数据结构对象的 tables。目前，数据限制部分不会以任何方式显示在屏幕上。我该怎么做？

Answer 1

看来您的蓝图并非 100% 正确。请使用 Drafter CLI tool 或 Apiary.io 来检查您的文件。

至于 MSON 语法 – 要指定属性的示例值，请使用：

+ SampleId: 123456789 (number, required)

要指定默认值，请使用：

+ SampleId: 123456789 (number, required)
    + Default: 0

回答您的问题：

在 Apiary.io 中，要在请求/响应中记录属性，只需将相关描述添加到负载级别，如您在：
```
    ### Get samples [GET]

    + Response 200 (application/json)
        + Attributes (SampleDTO)
```
目前在呈现 JSON 嵌套类型时存在错误 – 我们正在努力修复，请参阅
我们 (Apiary.io) 计划添加对单独呈现数据结构的支持。数据结构也应该出现在 API 的 Table 的 Content.

apiblueprint结构来实现所需的描述

apiblueprint structures to achieve desired description

apiblueprint

mson