2

我目前有这样的 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 的内容。然而，我将它内联或作为文档的单独部分存在，例如所有数据结构所在的位置。

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

4

1 回答 1

3

似乎你的蓝图不是 100% 正确的。请使用Drafter CLI 工具或 Apiary.io 对您的文件进行 lint。

至于 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 的目录中。

于 2015-04-27T16:40:25.847 回答