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 

我的问题是:

• 主要是我想要有请求和响应有效负载的表。我想实现布局:“响应”-> 表，其中包含作为响应有效负载的 json 对象字段。如果我输入“+ Attributes”(请参阅​​我的蓝图)，我设法显示它，但当您有一个 json 对象作为有效负载时，我不确定这是描述情况的正确方法。也许应该使用其他关键字？

• 当使用描述为“+ SampleProperties(SamplePropertiesDTO)”的字段呈现表格时，它在呈现的页面中显示为表格中的一行，并带有对象类型的 SampleProperties，并且无法找到 SamplePropertiesDTO 的内容在渲染的页面上。然而，我将其内嵌或作为文档的单独部分存在，例如所有数据结构所在的位置。

• 如果可能的话，我想单独显式显示数据结构对象的表。目前，数据限制部分不会以任何方式显示在屏幕上。我怎样才能做到这一点？

Answer 1

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

对于 MSON 语法 - 指定属性使用的示例值:

+ SampleId: 123456789 (number, required)

要指定默认值，请使用:

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

回答您的问题:

1. 在 Apiary.io 中，要在请求/响应中记录属性，只需将相关描述添加到负载级别，如下所示:

       ### Get samples [GET]
   
       + Response 200 (application/json)
           + Attributes (SampleDTO)
   

2. 当前渲染嵌套类型的 JSON 时存在错误 - 我们正在修复，请参阅 https://stackoverflow.com/a/29833106/634940

3. 我们 (Apiary.io) 计划添加对单独渲染数据结构的支持。数据结构也应出现在 API 的目录中。