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

Чтобы asnwer ваши quetions:

1. В Apiary.io, чтобы иметь атрибуты, документированные по запросу/ответу, просто добавьте соответствующее описание в оплату уровень нагрузки, как вы ahve в:

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

2. Существует в настоящее время ошибка в оказании JSON вложенных типов - мы работаем над решением этой проблемы, см https://stackoverflow.com/a/29833106/634940

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