5.12. ActiveDocs の作成

3scale toolbox を使用して、デベロッパーポータルの ActiveDocs の作成、更新、一覧表示、または削除を行います。

5.12.1. 新しい ActiveDocs の作成

OpenAPI 使用に準拠した API 定義から新しい ActiveDocs を作成するには、以下の手順を実施します。

  1. API 定義を 3scale に追加し、オプションで名前を付けます。 

    3scale activedocs create <remote> <activedocs-name> <specification>

    ActiveDocs の OpenAPI 仕様は必須で、以下の値のいずれかでなければなりません。

    • 利用可能なパスのファイル名
    • toolbox がコンテンツをダウンロードすることのできる URL。サポートされるスキームは http および https です。

    • stdin 標準入力ストリームから読み込む。これは、値に - を設定することで制御されます。

      ActiveDocs の作成時に、以下のオプションを使用します。 

      Options
    -d --description=<value>        Specify the description of
                                    the ActiveDocs
    -i --service-id=<value>         Specify the Service ID
                                    associated to the ActiveDocs
    -o --output=<value>             Output format on stdout: one
                                    of json|yaml
    -p --published                  Specify to publish the
                                    ActiveDocs on the Developer
                                    Portal. Otherwise it is hidden.
    -s --system-name=<value>        Specify the system-name of
                                    the ActiveDocs
       --skip-swagger-validations   Specify to skip validation
                                    of the Swagger specification
Options for ActiveDocs
    -c --config-file=<value>        toolbox configuration file.
                                    Defaults to $HOME/.3scalerc.yaml
    -h --help                       Print help for this command
    -k --insecure                   Proceed and operate even for
                                    server connections otherwise
                                    considered insecure
    -v --version                    Print the version of this command
       --verbose                    Verbose mode
  2. デベロッパーポータルに定義を 公開 します。

5.12.2. ActiveDocs の作成または更新

ActiveDoc が存在しない場合に新しく作成する、または新しい API 定義で既存の ActiveDocs を更新するには、以下のコマンドを使用します。 

3scale activedocs apply <remote> <activedocs_id_or_system_name>

ActiveDocs の更新時に、以下のオプションを使用します。 

Options
  -d --description=<value>              Specify the description of the
                                        ActiveDocs
       --hide                           Specify to hide the ActiveDocs
                                        on the Developer Portal
 -i --service-id=<value>                Specify the Service ID associated
                                        to the ActiveDocs
 -o --output=<value>                    Output format on stdout:
                                        one of json|yaml
    --openapi-spec=<value>              Specify the Swagger specification.
                                        Can be a file, a URL or '-' to read
                                        from stdin. This is a mandatory
                                        option when applying the ActiveDoc
                                        for the first time.
 -p --publish                           Specify to publish the ActiveDocs
                                        on the Developer Portal. Otherwise
                                        it is hidden
 -s --name=<value>                      Specify the name of the ActiveDocs
    --skip-swagger-validations=<value>  Specify whether to skip validation
                                        of the Swagger specification: true
                                        or false. Defaults to true.

Options for ActiveDocs
    -c --config-file=<value>           3scale toolbox configuration file:
                                       defaults to $HOME/.3scalerc.yaml
    -h --help                          Print help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Print the version of this command
       --verbose                       Verbose mode
注記

activedocs apply --skip-swagger-validations の動作が、3scale 2.8 で変更されました。activedocs apply を使用する既存のスクリプトを更新しなければならない場合があります。従来は、各 activedocs apply コマンドでこのオプションを指定しない場合、検証はスキップされませんでした。今回、--skip-swagger-validations はデフォルトで true になりました。

5.12.3. ActiveDocs の一覧表示

以下の項目を含め、デベロッパーポータルのすべての ActiveDocs に関する情報を取得するには、以下のコマンドを使用します。

  • ID
  • 名前
  • システム名
  • 説明
  • 公開済み (つまり、デベロッパーポータルに表示可能) かどうか
  • 作成日
  • 最終更新日

以下のコマンドにより、定義済みの ActiveDocs がすべて一覧表示されます。 

3scale activedocs list <remote>

ActiveDocs の一覧表示時に、以下のオプションを使用します。 

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml
    -s --service-ref=<value>      Filter the ActiveDocs by service
                                  reference
Options for ActiveDocs
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

5.12.4. ActiveDocs の削除

以下のコマンドにより、ActiveDocs が削除されます。 

3scale activedocs delete <remote> <activedocs-id_or-system-name>

ActiveDocs の削除時に、以下のオプションを使用します。 

Options for ActiveDocs
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode