apiblueprint - 目的の説明を実現するための 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 オブジェクトのフィールドを持つテーブル。「+ Attributes」を入力すると表示されましたが (設計図を参照)、ペイロードとして json オブジェクトがある場合、これが状況を説明する正しい方法であるかどうかはわかりません。たぶん、他のキーワードを使用する必要がありますか？
「+ SampleProperties(SamplePropertiesDTO)」と記述されたフィールドでテーブルをレンダリングすると、オブジェクト型の SampleProperties としてテーブルの行としてレンダリングされたページに表示され、SamplePropertiesDTO の内容はレンダリングされたページのどこにもありません。ただし、すべてのデータ構造が配置されている場所など、インラインまたはドキュメントの別のセクションとして存在する必要があります。
可能であれば、データ構造オブジェクトのテーブルを個別に明示的に表示したいと考えています。現在、データ構造セクションは画面に表示されていません。どうすればそれができますか？

apiblueprint - 目的の説明を実現するための apiblueprint 構造

1 に答える 1

Related

Reference