OpenAPIの設定(servers/tags/security/components)

nas2020/10/08

OpenAPIのservers/tags/security/componentsの設定のサンプルです。
(確認環境:Windows 10,Google Chrome,open api 3.0.3)

目次

サンプル OpenAPIとは
serversの設定
  tagsの設定
  componentsの設定
  securityの設定

OpenAPIとは

RESTful APIの標準的なフォーマットの仕様です。
JSONとYAMLがあります。

OpenAPI Initiative (OAI)が管理していてマイクロソフトやGoogle等も関わっています。

https://www.openapis.org/

Swaggerはツールで、APIドキュメントの生成やHTTPリクエストの作成やテストも行なえます。

 

serversの設定

serversの設定のサンプルです。サーバーへの接続情報です。

openapi: "3.0.3"

info:
  title: "Test1-API"
  version: "1.0.0"

servers:
- url: https://test1.com/
  description: Development server
- url: https://test2.com/
  description: Staging server
- url: https://test3.com{port}/
  description: Production server
  variables:
    port:
      enum:
        - '8443'
        - '443'
      default: '8443'

paths: {}

8,10,12行目は、サーバーのURLで3つあります。
12行目は、URLに加えてポート番号{port}があります。
{port}には、17行目または18行目の値が入ります。
デフォルトは19行目の8443です。

Swagger UIでは以下のように表示されます。

以下は、ポート番号です。

 

tagsの設定

tagsの設定のサンプルです。タグの単位でまとめます。

openapi: "3.0.3"

info:
  title: "Test1-API"
  version: "1.0.0"

tags:
    - name: syain
      description: "tag-ok"
paths:
  "/helloWorld":
    get:
      tags: ["syain"]
      responses:
        "200":
          description: "test-ok"
          content:
            application/json:
              schema:
                type: string
                example: "Hello World"

8行目は、syainというタグを設定しています。
13行目は、tagsのsyainを指定しています。

Swagger UIでは以下のように表示されます。メソッドはtagsの単位でまとまります。

Filter by tagの箇所は、タグ名で絞り込みができます。

 

componentsの設定

componentsの設定のサンプルです。
componentsは、変数(定数)のように使用できます。複数箇所から参照するとき等に使用します。

openapi: "3.0.3"

info:
  title: "Test1-API"
  version: "1.0.1"

paths:
  "/helloWorld":
    get:
      responses:
        "200":
          description: "test-ok"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/syain"
components:
  schemas:
    syain:
      type: string
      example: "Hello World"

16行目の$refは参照先を表します。
/components/schemas/syainは、17～19行目を指し、値として20行目と21行目を取得します。
16行目の$refは複数箇所に記述できるので20,21行目を複数箇所から参照できます。

 

securityの設定

securityの設定のサンプルです。

openapi: "3.0.3"

info:
  title: "Test1-API"
  version: "1.0.1"

paths:
  "/helloWorld":
    post:
      responses:
        "200":
          description: "test-ok"
          content:
            application/json:
              schema:
                type: string
                example: "Hello World"
      security:
      - test_apikey_auth: []
components:
  securitySchemes:
    test_apikey_auth:
      description: "APIKey"
      type: apiKey
      name: "testname"
      in: header

9行目のpostを実行したときに、19行目のセキュリティ設定が実行されます。
24,26行目は、apikeyとheaderでAPI Keyの認証を示しています。

他の認証の種類としては、OAuth2.0やOpen ID ConnectやJWT等があります。

Swagger UIでは以下のように表示されます。
Authorizeのマークが表示され、POSTの箇所にも鍵マークが表示されます。

以下は、OpenAPIの仕様書のリンクです。
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md

関連の記事

OpenAPIとSwaggerでhello worldを表示

△上に戻る