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

我的问题是：

主要是我希望有请求和响应有效负载的表。我想实现布局：“响应” - ＆gt;具有json对象字段的表，作为响应中的有效负载。如果我输入“+ Attributes”（参见我的蓝图），我设法显示它，但是当你有一个json对象作为有效载荷时，我不确定这是描述情况的正确方法。也许应该使用其他一些关键字？
当表格使用描述为“+ SampleProperties（SamplePropertiesDTO）”的字段进行渲染时，它在渲染页面中显示为表格中的一行，其中SampleProperties为object类型，SamplePropertiesDTO的内容无处可寻在呈现的页面上。然而，它是内联的或作为单独的文档部分，例如所有数据结构都在哪里。
如果可能，我想单独显示数据结构对象的表。目前，数据限制部分不以任何方式显示在屏幕上。我怎么能这样做？

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时存在一个错误 - 我们正在修复，请参阅https://stackoverflow.com/a/29833106/634940
我们（Apiary.io）计划分别添加对数据结构渲染的支持。数据结构也应出现在API的内容列表中。

apiblueprint结构，以实现所需的描述

1 个答案: