コンテンツにスキップ

基本構造

Swagger の定義は、JSON または YAML で記述できます。このガイドでは YAML の例のみを使用しますが、JSON でも同様に機能します。YAML で記述された Swagger 仕様の例は次のとおりです。

1
swagger: "2.0"
2
info:
3
  title: Sample API
4
  description: API description in Markdown.
5
  version: 1.0.0
6


7
host: api.example.com
8
basePath: /v1
9
schemes:
10
  - https
11


12
paths:
13
  /users:
14
    get:
15
      summary: Returns a list of users.
16
      description: Optional extended description in Markdown.
17
      produces:
18
        - application/json
19
      responses:
20
        200:
21
          description: OK

メタデータ

すべての Swagger 仕様は Swagger バージョンから始まり、2.0 が最新バージョンです。Swagger バージョンは、API 仕様の全体的な構造、つまり何をどのようにドキュメント化できるかを定義します。

1
swagger: "2.0"

次に、API の info ( title、description (オプション)、version (API バージョンであり、ファイルのリビジョンや Swagger バージョンではない) ) を指定する必要があります。

1
info:
2
  title: Sample API
3
  description: API description in Markdown.
4
  version: 1.0.0

version は任意の文字列にできます。セマンティック バージョン管理のように *major.minor.patch* を使用することも、*1.0-beta* や *2016.11.15* のような任意の形式を使用することもできます。description は複数行に対応しており、リッチ テキスト表現のためにGitHub Flavored Markdownをサポートしています。info は連絡先情報、ライセンス、その他の詳細のための他のフィールドもサポートしています。*参照:* 情報オブジェクト。

ベース URL

すべての API 呼び出しのベース URL は、schemes、host、および basePath を使用して定義されます。

1
host: api.example.com
2
basePath: /v1
3
schemes:
4
  - https

すべての API パスはベース URL を基準としています。たとえば、*/users* は実際には *https://api.example.com/v1/users* を意味します。*詳細情報:* API ホストとベース URL。

Consumes, Produces

consumes および produces セクションは、API でサポートされている MIME タイプを定義します。ルートレベルの定義は、個々の操作で上書きできます。

1
consumes:
2
  - application/json
3
  - application/xml
4
produces:
5
  - application/json
6
  - application/xml

詳細情報: MIME タイプ。

パス

paths セクションは、API の個々のエンドポイント (パス) と、これらのエンドポイントでサポートされる HTTP メソッド (操作) を定義します。たとえば、*GET /users* は次のように記述できます。

1
paths:
2
  /users:
3
    get:
4
      summary: Returns a list of users.
5
      description: Optional extended description in Markdown.
6
      produces:
7
        - application/json
8
      responses:
9
        200:
10
          description: OK

詳細情報: パスと操作。

パラメータ

操作には、URL パス ( /users/{userId} )、クエリ文字列 ( /users?role=admin )、ヘッダー ( X-CustomHeader: Value )、およびリクエストボディを介して渡せるパラメーターがあります。パラメーターのタイプ、形式、必須かオプションか、その他の詳細を定義できます。

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Returns a user by ID.
5
      parameters:
6
        - in: path
7
          name: userId
8
          required: true
9
          type: integer
10
          minimum: 1
11
          description: Parameter description in Markdown.
12
      responses:
13
        200:
14
          description: OK

詳細情報: パラメーターの記述。

応答

各操作について、200 OK や 404 Not Found などの可能なステータス コードと、応答ボディの schema を定義できます。スキーマはインラインで定義することも、$ref を介して外部定義から参照することもできます。さまざまなコンテンツ タイプについて、応答例を提供することもできます。

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Returns a user by ID.
5
      parameters:
6
        - in: path
7
          name: userId
8
          required: true
9
          type: integer
10
          minimum: 1
11
          description: The ID of the user to return.
12
      responses:
13
        200:
14
          description: A User object.
15
          schema:
16
            type: object
17
            properties:
18
              id:
19
                type: integer
20
                example: 4
21
              name:
22
                type: string
23
                example: Arthur Dent
24
        400:
25
          description: The specified user ID is invalid (e.g. not a number).
26
        404:
27
          description: A user with the specified ID was not found.
28
        default:
29
          description: Unexpected error

詳細情報: 応答の記述。

入力および出力モデル

グローバル definitions セクションでは、API で使用される共通のデータ構造を定義できます。これらは、リクエストボディとレスポンスボディの両方で schema が必要とされるたびに $ref を介して参照できます。たとえば、この JSON オブジェクトは次のようになります。

1
{
2
  "id": 4,
3
  "name": "Arthur Dent"
4
}

次のように表現できます。

1
definitions:
2
  User:
3
    properties:
4
      id:
5
        type: integer
6
      name:
7
        type: string
8
    # Both properties are required
9
    required:
10
      - id
11
      - name

そして、次のようにリクエストボディのスキーマとレスポンスボディのスキーマで参照されます。

1
paths:
2
  /users/{userId}:
3
    get:
4
      summary: Returns a user by ID.
5
      parameters:
6
        - in: path
7
          name: userId
8
          required: true
9
          type: integer
10
      responses:
11
        200:
12
          description: OK
13
          schema:
14
            $ref: "#/definitions/User"
15
  /users:
16
    post:
17
      summary: Creates a new user.
18
      parameters:
19
        - in: body
20
          name: user
21
          schema:
22
            $ref: "#/definitions/User"
23
      responses:
24
        200:
25
          description: OK

認証

securityDefinitions と security キーワードは、API で使用される認証方法を記述するために使用されます。

1
securityDefinitions:
2
  BasicAuth:
3
    type: basic
4


5
security:
6
  - BasicAuth: []

サポートされている認証方法は次のとおりです。

  • 基本認証
  • API キー (ヘッダーまたはクエリパラメーターとして)
  • OAuth 2 の一般的なフロー (implicit、password、application、access code)

詳細情報: 認証。

お探しのものが見つかりませんでしたか？ コミュニティに質問する
間違いを見つけましたか？ お知らせください