Asciidoctor での作業

このセクションでは、特に Spring REST Docs に関連する Asciidoctor の操作の特徴について説明します。

Asciidoc はドキュメント形式です。Asciidoctor は、Asciidoc ファイル (末尾が .adoc) からコンテンツ (通常は HTML) を生成するツールです。

リソース

スニペットを含める

このセクションでは、Asciidoc スニペットを含める方法について説明します。

オペレーションに複数のスニペットを含める

operation というマクロを使用すると、特定の操作用に生成されたスニペットのすべてまたは一部をインポートできます。このマクロは、プロジェクトのビルド構成に spring-restdocs-asciidoctor を含めることで利用可能になります。spring-restdocs-asciidoctor を使用するには、AsciidoctorJ 3.0 が必要です。

マクロのターゲットは操作の名前です。最も単純な形式では、次の例に示すように、マクロを使用して操作のすべてのスニペットを含めることができます。

operation::index[]

操作マクロは snippets 属性もサポートしています。これを使用して、含めるスニペットを選択できます。属性の値はカンマ区切りのリストです。リスト内の各エントリは、含めるスニペットファイルの名前（.adoc サフィックスを除く）である必要があります。例: 次の例に示すように、curl、HTTP リクエスト、HTTP レスポンスのスニペットのみを含めることができます。

operation::index[snippets='curl-request,http-request,http-response']

前の例は、次と同等です。

[[example_curl_request]]
= Curl request

include::{snippets}/index/curl-request.adoc[]

[[example_http_request]]
= HTTP request

include::{snippets}/index/http-request.adoc[]

[[example_http_response]]
= HTTP response

include::{snippets}/index/http-response.adoc[]

セクションのタイトル

operation マクロを使用して組み込まれるスニペットごとに、タイトル付きのセクションが作成されます。次の組み込みスニペットには、デフォルトのタイトルが用意されています。

スニペット タイトル

curl-request

Curl リクエスト

http-request

HTTP リクエスト

http-response

HTTP レスポンス

httpie-request

HTTPie リクエスト

links

リンク

request-body

リクエストボディー

request-fields

リクエストフィールド

response-body

レスポンスボディ

response-fields

レスポンスフィールド

上記の表に記載されていないスニペットの場合、- 文字をスペースに置き換え、最初の文字を大文字にすることで、デフォルトのタイトルが生成されます。例: custom-snippet will be 「カスタムスニペット」という名前のスニペットのタイトル。

ドキュメント属性を使用して、デフォルトのタイトルをカスタマイズできます。属性の名前は operation-{snippet}-title である必要があります。例: curl-request スニペットのタイトルを「サンプルリクエスト」にカスタマイズするには、次の属性を使用できます。

:operation-curl-request-title: Example request

個々のスニペットを含める

インクルードマクロ (英語) は、ドキュメントに個々のスニペットを含めるために使用されます。snippets 属性 ( ビルド構成で構成された spring-restdocs-asciidoctor によって自動的に設定される) を使用して、スニペットの出力ディレクトリを参照できます。次の例は、その方法を示しています。

include::{snippets}/index/curl-request.adoc[]

テーブルのカスタマイズ

スニペットの多くには、デフォルト構成のテーブルが含まれています。テーブルの外観は、スニペットが含まれている場合に追加の構成を提供するか、カスタムスニペットテンプレートを使用してカスタマイズできます。

列のフォーマット

Asciidoctor は、表の列の書式設定 (英語) を豊富にサポートしています。次の例に示すように、cols 属性を使用してテーブルの列の幅を指定できます。

[cols="1,3"] (1)
include::{snippets}/index/links.adoc[]

タイトルの設定

. を前に付けた行を使用して、テーブルのタイトルを指定できます。次の例は、その方法を示しています。

.Links (1)
include::{snippets}/index/links.adoc[]

表の書式設定の問題を回避する

Asciidoctor は、| 文字を使用してテーブル内のセルを区切ります。これは、| をセルの内容に表示したい場合に問題を引き起こす可能性があります。| をバックスラッシュでエスケープすることで、この問題を回避できます。つまり、| ではなく \| を使用します。

デフォルトの Asciidoctor スニペットテンプレートはすべて、tableCellContent という名前の Mustache ラムバを使用して、このエスケープを自動的に実行します。独自のカスタムテンプレートを作成する場合は、このラムバを使用することをお勧めします。次の例は、description 属性の値を含むセルで | 文字をエスケープする方法を示しています。

| {{#tableCellContent}}{{description}}{{/tableCellContent}}

参考文献

テーブルのカスタマイズの詳細については、Asciidoctor ユーザーマニュアルのテーブルセクション (英語) を参照してください。