基本構造

OAS 2 このページは、OpenAPI仕様バージョン2（旧Swagger）に適用されます。最新バージョンについては、OpenAPI 3のページをご覧ください。

基本構造

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

swagger: "2.0"
info:
  title: Sample API
  description: API description in Markdown.
  version: 1.0.0

host: api.example.com
basePath: /v1
schemes:
  - https

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in Markdown.
      produces:
        - application/json
      responses:
        200:
          description: OK

メタデータ

すべてのSwagger仕様は、Swaggerバージョン（最新バージョンは2.0）から始まります。Swaggerバージョンは、API仕様の全体的な構造（何を文書化できるか、どのように文書化するか）を定義します。

swagger: "2.0"

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

info:
  title: Sample API
  description: API description in Markdown.
  version: 1.0.0

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

ベースURL

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

host: api.example.com
basePath: /v1
schemes:
  - https

すべてのAPIパスは、ベースURLからの相対パスです。たとえば、/usersは実際にはhttps://api.example.com/v1/usersを意味します。詳細：APIホストとベースURL。

Consumes, Produces

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

consumes:
  - application/json
  - application/xml
produces:
  - application/json
  - application/xml

詳細：MIMEタイプ。

パス

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

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in Markdown.
      produces:
        - application/json
      responses:
        200:
          description: OK

詳細：パスと操作。

パラメーター

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

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - in: path
          name: userId
          required: true
          type: integer
          minimum: 1
          description: Parameter description in Markdown.
      responses:
        200:
          description: OK

詳細：パラメーターの記述。

レスポンス

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

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - in: path
          name: userId
          required: true
          type: integer
          minimum: 1
          description: The ID of the user to return.
      responses:
        200:
          description: A User object.
          schema:
            type: object
            properties:
              id:
                type: integer
                example: 4
              name:
                type: string
                example: Arthur Dent
        400:
          description: The specified user ID is invalid (e.g. not a number).
        404:
          description: A user with the specified ID was not found.
        default:
          description: Unexpected error

詳細：レスポンスの記述。

入力および出力モデル

グローバルなdefinitionsセクションを使用すると、APIで使用される一般的なデータ構造を定義できます。リクエストボディとレスポンスボディの両方で、schemaが必要な場合はいつでも$refを介して参照できます。たとえば、このJSONオブジェクト

{
  "id": 4,
  "name": "Arthur Dent"
}

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

definitions:
  User:
    properties:
      id:
        type: integer
      name:
        type: string
    # Both properties are required
    required:  
      - id
      - name

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

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - in: path
          name: userId
          required: true
          type: integer
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/User'
  /users:
    post:
      summary: Creates a new user.
      parameters:
        - in: body
          name: user
          schema:
            $ref: '#/definitions/User'
      responses:
        200:
          description: OK

認証

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

securityDefinitions:
  BasicAuth:
    type: basic

security:
  - BasicAuth: []

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

基本認証
APIキー（ヘッダーまたはクエリパラメーターとして）
OAuth 2の一般的なフロー（暗黙的、パスワード、アプリケーション、アクセスコード）

詳細：認証。

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