OpenAPI - mgn901 / めがね901

OpenAPI

RESTful APIの仕様書の仕様

openapi.jsonまたはopenapi.yamlというファイル名で作成する。

OpenAPI Documentの全体像

openapi、info、servers、paths、components、security、tags、externalDocs

code:yaml

openapi: '3.0.2'

info:

title: Sbullasy HTTP API

# summary:

# description:

# termsOfService:

# contact:

# license:

version: '0.1.0'

# jsonSchemaDialect:

servers:

- url: https://{host}/api/v1

# description:

variables:

host:

# enum:

default: sbullasy.mgn901.com

# description:

paths:

/users:

# $ref:

# summary:

# description:

get:

# tags:

# summary:

# description:

# externalDocs:

# operationId:

parameters:

- $ref: "#/components/parameters/limit"

- $ref: "#/components/parameters/offset"

# requestBody:

responses:

200:

description: users to be returned

# headers:

content:

application/json:

schema:

$ref: "#/components/schemas/userSchema"

# example

# examples:

# links:

# callbacks:

# deprecated:

security:

- cookie_auth: []

- bearer_auth: []

# servers:

# parameters:

# webhooks:

components:

schemas:

userSchema:

type: object

properties:

id:

type: string

email:

type: string

name:

type: string

displayName:

type: string

createdAt:

type: number

ipRegisteredFrom:

type: string

registrationExpiresAt:

type: number

nullable: true

verificationExpiresAt:

type: number

nullable: true

# groupSchema:

# itemSchema:

# responses:

parameters:

limit:

in: query

# description:

# required: false # default

# deprecated:

# allowEmptyValue: false # default

style: form

explode: true

# allowReserved: false # default

schema:

type: number

# example:

# examples:

offset:

in: query

style: form

explode: true

schema:

type: number

# examples:

# requestBodies:

# headers:

securitySchemes:

cookie_auth:

type: apiKey

# description:

in: cookie

bearer_auth:

type: http

scheme: bearer

# links:

# callbacks:

# pathItems:

# security:

# tags:

# externalDocs:

openapi

そのOpenAPI Documentが従っているOpenAPI仕様のバージョンを書く。

code:openapi.yaml

openapi: '3.0.2'

info

そのAPIの基本情報を書く。

titleとversionが必須。

versionはAPI自体のバージョンを書く。

code:openapi.yaml

info:

title: Sbullasy HTTP API

# summary:

# description:

# termsOfService:

# contact:

# license:

version: '0.1.0'

servers

APIを動かしているサーバーの情報（Server Variable Object）を配列形式で並べる。

urlはサーバーのURLを指す。URLに{変数名}を含めると、Swagger UIでその部分を動的に変更してAPIを試すことができる。

https://gyazo.com/033ed9a0dccee0dbccd5af50b7076377

code:openapi.yaml

servers:

- url: https://{host}/api/v1

# description:

variables:

host:

# enum:

default: sbullasy.mgn901.com

# description:

paths

エンドポイントの定義を書く。

全体像

code:yaml

paths:

パス名:

メソッド名:

パス名

{変数名}で変数を含めることができる。変数名の要件はParameter Objectで指定できる。

Operation Object

parameters: Parameter Object | Reference Objectの配列

requestBody: Request Body Object | Reference Object

responses: キーをステータスコード、値をResponse Object | Reference Objectとする辞書

security

そのエンドポイントのそのメソッドを呼び出すのに必要な認証の配列（Security Requirement Objectの配列）

Security Requirement Object: キーを#/components/securitySchemesのキーの1つとする、値をスコープ名とする辞書。キーは1つだけ。

Parameter Object

in: そのパラメータを書き込んでいる場所。"query" |"header" | "path" | "cookie"

name

inが"query": クエリパラメータの名前

inが"path": パスに含まれる変数の名前

inが"header": ヘッダー名

inが"cookie": Cookieの名前

style

inの値とschemaのtypeの値によって適切な値が決まる。OpenAPI Specification - Version 3.0.3 | Swaggerに表が載っているので参照されたし。

普通の使い方ならこうなりそう。mgn901.icon

inが"query" | "cookie": "form"

inが"path" | "header": "simple"

explode

inの値、schemaのtypeの値、styleの値によって適切な値が決まる。OpenAPI Specification - Version 3.0.3 | Swaggerに表が載っているので参照されたし。

Requst Body Object

content: キーをメディアタイプ、値をMedia Type Objectとする辞書。

required: リクエストボディが必須であるかどうか。boolean

Response Object

description: 何が返されるのかの説明。必須。

content: キーをメディアタイプ、値をMedia Type Objectとする辞書。

Media Type Object

schema: Schema Object（JSON Schema）

Reference Objectについて

よく使うParameter Object、Request Body Object、Response Objectを#/componentsにまとめておいて、ほかの部分から参照できるようにする仕組みがある。

下の例だと$refというキーを持つオブジェクトがReference Objectで、他のオブジェクトを参照している。

code:openapi.yaml

paths:

/users:

# $ref:

# summary:

# description:

get:

# tags:

# summary:

# description:

# externalDocs:

# operationId:

parameters:

- $ref: "#/components/parameters/limit"

- $ref: "#/components/parameters/offset"

# requestBody:

responses:

200:

description: users to be returned

# headers:

content:

application/json:

schema:

$ref: "#/components/schemas/userSchema"

# example

# examples:

# links:

# callbacks:

# deprecated:

security:

- cookie_auth: []

- bearer_auth: []

# servers:

# parameters:

components

スキーマなどをまとめられる。

code:yaml

components:

schemas:

userSchema:

type: object

properties:

id:

type: string

email:

type: string

name:

type: string

displayName:

type: string

createdAt:

type: number

ipRegisteredFrom:

type: string

registrationExpiresAt:

type: number

nullable: true

verificationExpiresAt:

type: number

nullable: true

# groupSchema:

# itemSchema:

# responses:

parameters:

limit:

in: query

# description:

# required: false # default

# deprecated:

# allowEmptyValue: false # default

style: form

explode: true

# allowReserved: false # default

schema:

type: number

# example:

# examples:

offset:

in: query

style: form

explode: true

schema:

type: number

# examples:

# requestBodies:

# headers:

securitySchemes:

cookie_auth:

type: apiKey

# description:

in: cookie

bearer_auth:

type: http

scheme: bearer

# links:

# callbacks:

# pathItems:

securitySchemes

Authenticationに認証方式ごとの記述方法の説明が載っている。

参考にした資料

SmartBear Software "OpenAPI Specification - Version 3.0.3 | Swagger"

株式会社ペライチ「Open API はじめました」

JSON Schema