Swaggerテキストの説明をフォーマットする
1. 序章
OpenAPI仕様（以前のSwagger仕様）は、REST APIドキュメント言語を標準化し、プラットフォームに依存しません。 YAMLまたはJSON形式のOpenAPIドキュメントを作成できます。
一方、 Swagger は、標準を実装および操作するためのツールのコレクションです。 無料のもの、オープンソースのもの、商用のものがあります。 これらのツールは、REST APIの設計、文書化、および使用に役立ちます。
この記事では、OpenAPIドキュメントのテキスト説明をフォーマットする方法を学習します。
2. OpenAPIエディター
いくつかのツールがOpenAPIドキュメントの作成をサポートしています。 いくつかの人気のあるツールは次のとおりです。
他のいくつかのエディターがOpenAPIドキュメントの作成をサポートしています。ただし、最も一般的で広く使用されているエディターはSwagger Editorです。したがって、SwaggerEditorを使用したOpenAPIドキュメントのフォーマットについて学習します。
3. YAMLと JSONフォーマット
OpenAPIドキュメントはJSONまたはYAML形式のいずれかで表されます。 ただし、YAMLを使用している場合、ドキュメントのフォーマットは簡単です。
たとえば、単語または文を見出しとしてマークするには、YAMLで以下のスニペットを使用します。
description: |
# This is a heading in *italics*
This is in the next line
This is in **bold**YAML表現は|を使用します （パイプ）スカラーリテラルを表します。これは複数行にすることができます。
それでは、JSONで同じことを定義しましょう。
{
"description": "# This is a heading in *italics*\nThis is in the next line\n\nThis is in **bold**
}比較すると、JSON表現では、エスケープシーケンスによってフォーマットが直感に反します。 今後は、YAMLで記述されたOpenAPI仕様ドキュメントのフォーマット手法についてのみ説明します。
最後に、OpenAPI仕様では、すべてのレベルでdescriptionフィールドのフォーマットが可能です。 したがって、仕様によれば、 description フィールドが許可されている場合はいつでも、それをフォーマットでき、descriptionフィールドはCommonMarkフォーマットスタイルに準拠します。
それでは、APIドキュメントをフォーマットして拡張しましょう。
4. 見出し
私たちが使うように
に
HTMLの見出しでは、マークダウン見出しを使用してテキストを強調表示できます。 ＃は見出しを表します
＃が後に続くテキストは、######が伴うテキストよりも明るく大きくなります。
たとえば、YAMLについて考えてみます。
openapi: 3.0.1
info:
title: Petstore
description: |
# Pet Store APIs
## This is a sample Petstore server
### Contains APIs to manage the pet store
#### Note that the APIs support Basic Authentication and OAUTH
##### The samples contain Request and Response models
###### There are status codes defined as wellSwaggerは、テキストを次のようにレンダリングします。
5. テキスト強調
description テキストの読みやすさを向上させるために、太字または斜体にすることで強調することができます。
テキストを**と**の間、または__と__の間に配置すると、テキストが太字になります。 同様に、テキストを*と*または_と_内に配置すると、テキストは斜体になります。 たとえば、YAMLの場合：
openapi: 3.0.1
info:
title: Petstore
description: |
## This document contains
**Pet Store APIs** *Note: All the APIs return application/json*.
__User APIs__ _Note: These APIs contain attachments and only support image/jpeg as the content type_SwaggerはYAMLを次のようにレンダリングします。
6. テーブル
次に、OpenAPIドキュメントにテーブルを追加する方法を見てみましょう。
テーブルをレンダリングするために従うべき一連のルールがあります。
たとえば、POSTAPIのHTTPステータスコードを定義するテーブルを追加しましょう。
paths:
/pet:
post:
tags:
- pet
description: |
**The below table defines the HTTP Status codes that this API may return**
| Status Code | Description | Reason |
| ---------------- | ------------| -----------------------------------|
| 201 | CREATED | If a pet is created successfuly. |
| 400 | BAD REQUEST | If the request is not valid. |
| 401 | UNAUTHORIZED| If the credentials are invalid. |Swaggerは以下を生成します：
7. リスト
次に、リストを含むように説明テキストをフォーマットする方法を見てみましょう。
7.1. 注文リスト
description: |
1. Available
3. Pending
1. Solddescription: |
1. Available
200. Pending
30. Solddescription: |
1. Available
100. Pending
50. Sold同じ出力を生成します。
1. Available
2. Pending
3. Soldアイテムの番号付けは、開始アイテムによって異なります。 たとえば、アイテム番号を 10 で始めると、次のアイテムには 11 、 12 、13などの番号が付けられます。 以下のYAML：
description: |
10. Available
120. Pending
50. Sold生成：
10. Available
11. Pending
12. Sold同様に、同じルールが順序付けられたサブリストにも適用されます。 サブリストをその親アイテムにインデントします。 例として、YAMLについて考えてみます。
description: |
1. Available
2. Pending
1. Pending in Store
200. Pending in Cart
3. Soldこれは以下を生成します：
1. Available
2. Pending
1. Pending in Store
2. Pending in Cart
3. Sold7.2. 順不同リスト
*（アスタリスク）または+（プラス）または–（ハイフン）を使用して、順序付けられていないリストを作成します。 つまり、リスト内の各項目は、これらの記号の1つで始まる必要があります。 例えば：
description: |
* Available
* Pending
* Sold
description: |
+ Available
+ Pending
+ Sold
description: |
- Available
- Pending
- Sold上記のすべてのスニペットは、順序付けられていないリストを生成します。
同様に、 順序付けされていないサブリストを生成するには、アイテムを親アイテムでインデントし、*（アスタリスク）または+（プラス）または–（ハイフン）で始めます。
- Available
- Pending
* Pending in Store
+ Pending in Cart
- Soldサブリストを含む順序なしリストを生成します。 区切り文字の組み合わせに注意してください。 同じ結果を生成する区切り文字を混在させることができます。
最後に、これらすべてをまとめてYAMLに配置しましょう。
/pet/findByStatus:
get:
summary: Finds Pets by status
description: |
__Below is the list of valid status of the Pet__
1. Available
2. Pending
1. Pending in the cart
2. Pending in the store
3. Sold
**Below is the list of HTTP Status code this API may return**
* 200 - OK
* 400 - Bad Request. The API returns below status codes related to content-type and accept headers
+ 415 - Unsupported Media Type
- 406 - Not Acceptable
* 401 - Unauthorized
* 405 - Method not supportedこのYAMLは以下を生成します：
8. その他
8.1. 改行と段落
description: |
Returns a single pet.
*Note: The API may throw a HTTP 404 if there are no pets found with a given id.*
The API returns a 200 OK if there is a pet with given Id. Also, this API returns the status of the pet
このYAMLは以下を生成します：
8.2. コード
description: |
The API returns user details for a given username.
The API can be invoked using *curl* like below:
```
curl --header accept: application/json -u username:password http://localhost:8080/api/v2/user/jhondoe
```
**Sample Output**
```
{
"id": 2,
"username": "jhondoe"
"email": "[email protected]"
}
```8.3. 画像
description: |
# Pet Store APIs
9. 結論
この記事では、OpenAPIドキュメントのdescriptionフィールドをフォーマットする方法を見てきました。 YAMLスカラーリテラルは、ドキュメント全体で説明のフォーマットを有効にします。 したがって、OpenAPIドキュメントには、リスト、テーブル、画像など、サポートされている構成の一部またはすべてを含めることができます。
したがって、APIを文書化すると、使いやすさが向上します。 結局のところ、十分に文書化され、フォーマットされたAPIは、簡単に統合して使用できるようにするために私たち全員が望んでいるものです。
