apiblueprint structures to achieve desired description

I currently have such an API blueprint, but i can not achieve proper rendering.

    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

My questions are:

Mainly I would like to have tables for request and response payloads. I would like to achieve layout: "Response" -> table with fields of json object that comes as payload in response. I managed to get it displayed if I put "+ Attributes" (see my blueprint), but I am not sure this is a correct way to describe the situation, when you have a json object as payload. Maybe some other keyword should be used?
When table is rendered with field described as "+ SampleProperties(SamplePropertiesDTO)" it is displayed in rendered page as a line in the table, with as SampleProperties of type object, and contents of SamplePropertiesDTO is nowhere to be found on rendered page. I however it to be present inline or as separate section of documentation, e.g. where all data structures are located.
I want to explicitly show tables for Data structures objects separately, if possible. Presently Data strictures section is not show on screen in any way. How I could do that?

Solution

Seems your blueprint is not 100% correct. Please use Drafter CLI tool or Apiary.io to lint your file.

As for MSON syntax – to specify a sample value of a property use:

+ SampleId: 123456789 (number, required)

To specify a default value use:

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

To asnwer your quetions:

In Apiary.io, to have attributes documented on request / response simply add the relevant description to the payload level as you ahve in:
```
    ### Get samples [GET]

    + Response 200 (application/json)
        + Attributes (SampleDTO)
```
There is currently a bug in rendering JSON of nested types – we are working on a fix, see https://stackoverflow.com/a/29833106/634940
We (Apiary.io) plan to add support for rendering Data Structures seperatately. Data structures should also appear in API's Table of Content.