Структуры 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 

Мои вопросы:

• В основном я хотел бы иметь таблицы для запросов и ответов. Я хотел бы добиться макета: "Response" -> таблица с полями объекта JSON, который приходит в качестве полезной нагрузки в ответ. Мне удалось отобразить его, если я поставил "+ атрибуты" (см. Мой план), но я не уверен, что это правильный способ описать ситуацию, когда в качестве полезной нагрузки используется объект 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 вложенных типов - мы работаем над исправлением, см. /questions/13672583/popyitka-opisat-zapros-i-otvet-s-ispolzovaniem-struktur-dannyih-v-api-blueprint/13672593#13672593

3. Мы (Apiary.io) планируем добавить поддержку рендеринга структур данных отдельно. Структуры данных также должны отображаться в таблице содержания API.