# 必須
# OpeｎAPIのどのバージョンを利用して記述しているかを定義する。 
# バージョンはセマンティックバージョニングで定義されており、記述もセマンティックバージョニングに従って記述する。
openapi: "3.0.0"
 
# 必須
# APIのメタデータを定義する。
info:
  ...
 
# APIを提供するサーバーを配列で記述する。
servers:
  ...

# APIを整理するために利用するタグを定義する。 
tags:
  ...
 
# 必須
# APIとして利用可能なパスおよび操作を定義する
paths:
  ...

# いろいろなオブジェクトをコンポーネントとして再利用可能な形で定義する。
components:
  ...

info:
  title: "Sample API"
  description: "Sample API provides sample function."
  version: "1.0.0"

postid: ""
tag:
  - product # GoアプリケーションのhandlerやTypeScriptのclassの単位となる

postid: ""
tag:
  - products

postid: ""
tag:
  - user
  - product

# GET /products
operationId: getProducts

# GET /products/:product_id
operationId: getProductByProductId

# POST /products
operationId: postProducts

# PUT /products/:product_id
operationId: putProduct

# DELETE /product/:product_id
operationId: deleteProduct

description: IDを指定して商品情報を取得する。

summary: XXX-0001 商品参照

security: []

security:
  - isAuthorized: []

securityDefinitions:
  isAuthorized:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://example.com/authorize'
    tokenUrl: 'https://example.com/.well-known/jwks.json'

- in: path
  name: product_id
  type: string
  description: プロダクトID
  required: true
- in: query
  name: product_types
  type: array
  description: プロダクト種別
- in: query
  name: is_defective
  type: boolean
  description: 不良品フラグ

- in: path
  name: productId # キャメルケースはNG
  type: string
  description: プロダクトID
  required: false # 不要
- in: query
  name: product_type_list # xxx_listはNG
  type: array
  description: プロダクト種別
- in: query
  name: defective_flag # trueとfalseがどちらの状態を示すのか不明瞭であるため非推奨
  type: boolean
  description: 不良品フラグ

parameters:
  - in: body
    name: body
    required: true
    schema:
      $ref: '#/definitions/postProductsRequest'

parameters:
  - in: body
    name: postProductsBody
    required: false # 不要
    schema:
      type: object # TypeScriptのInterfaceの自動生成時に型が適切に定義されない
      properties:
        product_name:
          type: string

# ex. enum
name: gender
type: string
enum:
  - '00'
  - '01'
  - '02'
description: |
  性別
    00: 不明
    01: 男
    02: 女

created_date:
    type: string
    example: '2020-01-31'
    format: date

created_date_time:
    type: string
    example: '2020-01-31T23:59:59+09:00'
    format: date-time

created_date_time:
    type: string
    example: '2020-01-31T23:59:59.000+09:00'
    pattern: '^((?:[1-9][0-9]*)?[0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\.[0-9][0-9][0-9])[+|-]([0-9][0-9]:[0-9][0-9])$'`

created_time:
    type: string
    example: 23:59
    pattern: '^(2[0-3]|[01][0-9]):([0-5][0-9])$'

getProductsResponse:
  allOf:
    - type: object
      properties:
        products:
          type: array
          items:
            $ref: "#/definitions/product"
        required:
          - products
    - $ref: "#/definitions/pagination"

getProductsResponse:
  type: array # TypeScriptのInterfaceが適切に定義されません
  items:
    product:
      type: object
        properties:
          product_id:
            type: string
            # required: true を定義しないとundefined許容の変数となり不要なType Guardが必要になる
          product_name:
            type: string

200:
  description: OK
  schema:
    $ref: '#/definitions/getProductsResponse'
  examples:
    application/json: # Mockサーバのレスポンスになるためフロントエンド開発者も編集する
      products:
        - product_name: Example Product
          create_date: '2020-01-01'
400:
  description: Bad Request
  schema:
    $ref: '#/definitions/ErrorResponse'

500:
  description: Internal Server Error
  schema:
    $ref: '#/definitions/ErrorResponse'

# POST /products
postProductRequest:
  type: object
  properties:
    proeuct_name:
      type: string
  required:
    - product_name

# PUT /products/:product_id
putProductRequest:
  type: object
  properties:
    proeuct_id:
      type: string
    proeuct_name:
      type: string
  required:
    - product_id

# GET /products
getProductResponse:
  type: object
  properties:
    proeucts:
      type: array
      items:
        $refs: "#/definitions/product"

# GET /products/:product_id
responses:
  200:
    description: OK
      schema:
        $ref: "#/definitions/product" # リソースモデルをそのまま利用する場合は不要

pagination:
  type: object
  properties:
    total_counts:
      type: integer
    offset:
      type: integer
    limit:
      type: integer
  required:
    - total_counts
    - offset
    - limit

paths:
  /hoge:
    # post/put/delete
    post:
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                foo:
                  type: string
                bar:
                  type: integer
                baz: # ファイル
                  type: string
                  format: binary

paths:
  /hoge:
    # post/put/delete
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                foo:
                  type: string
                bar:
                  type: integer

paths:
  /hoge:
    post:
      requestBody:
        content:
          application/xml:
            schema:
              $ref: "#/components/schemas/piyo" 

components:
  schemas:
    piyo:
      type: object
      properties:
        foo:
          type: string
        bar:
          type: integer

paths:
  /hoge:
    post:
      requestBody:
        content:
          image/jpeg:
            schema:
              type: string
              format: binary

paths:
  /hoge:
    post:
      requestBody:
        content:
          image/*:
            schema:
              type: string
              format: binary

servers:
  - url: https://example.com/api/v1

servers:
  - url: http://example.com/api/v1
  - url: https://example.com/api/v1

servers:
  - url: "{protocol}://test{number}.example.com:{port}/api/v1" 
    variables:
      protocol:
        default: https
        enum:
          - http
          - https
      number:
        default: "1" 
      port:
        default: "443" 
        enum:
          - "443" 
          - "8080" 

paths:
  /hoge:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/piyo" 
          application/xml:
            schema:
              $ref: "#/components/schemas/piyo" 
      responses:
        "200":
          description: ok

components:
  schemas:
    piyo:
      type: object
      properties:
        foo:
          type: object
          properties:
            bar:
              type: string

components:
  schemas:
    # 共通モデル

  parameters:
    # GET などで取得範囲を変更するときなどに利用

  requestBodies:
    # 共通で使う POST データ

  responses:
    # 共通のレスポンス定義、 paths の中で利用

paths:
  /hoge:
    get:
      security:
        - BasicAuth: [] # 配列内は権限のスコープ。OAuth と OpenIDConnect 以外は空配列
      responses:
        "200":
          description: ok
components:
  securitySchemes:
    BasicAuth: # 任意の識別子
      type: http
      scheme: basic

paths:
  /hoge:
    get:
      security: 
        - OAuth2:
          - read
      responses:
        "200":
          description: ok
    post:
      security: 
        - OAuth2:
          - write
      responses:
        "200":
          description: ok

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: "読み取り権限"
            write: "書き込み権限"
            create_review: "Post new review."

paths:
  /hoge:
    get:
      security: 
        - CookieAuth: []
      responses:
        "200":
          description: ok

components:
  securitySchemes:
    CookieAuth:
      type: apiKey
      in: cookie
      name: SSID

paths:
  /hoge:
    get:
      security: 
        - bearer: []
      responses:
        "200":
          description: ok

components:
  securitySchemes:
    bearer:
      type: http
      description: JWT Token Authenticatio
      scheme: bearer
      bearerFormat: JWT

paths:
  /hoge:
    get:
      security: 
        - apikey: []
      responses:
        "200":
          description: ok

  #-------------------------------
  # Reusable security
  #-------------------------------
  securitySchemes:
    apikey:
      type: apiKey
      name: x-api-key
      in: header
      description: API Key Authentication

paths:
  /hoge:
    get:
      security: 
        - sample_oidc_auth: []
      responses:
        "200":
          description: ok

components:
  securitySchemes:
    sample_oidc_auth:
      type: openIdConnect
      openIdConnectUrl: "https://oidc.sample.com/signin"

paths:
  "/shops/{shopId}/reviews":
    post:
      summary: "Get specified shop's reviews."
      description: "Get specified shop's reviews."
      tags:
        - shops
      deprecated: false
      parameters:
        ...
      requestBody:
        ...
      responses:
        ...
      security:
        ...

components:
  schemas:
    Order:
      description: '注文'
      type: object
      required:
        - order_id
        - description
      properties:
        order_id:
          title: "注文 ID"
          type: string
          example: "a1b2c3"
        description:
          title: "注文に関するあれこれ"
          type: string
          example: "24 -TWENTY FOUR- 10周年記念コンプリートDVD-BOX"

components:
  schemas:
    OrderId:
      description: '注文 ID'
      type: object
      required:
        - order_id
      properties:
        order_id:
          title: '注文 ID'
          type: string
          example: 'a1b2c3'

    OrderModel:
      description: '注文モデル'
      type: object
      required:
        - description
      properties:
        description:
          title: '注文に関するあれこれ'
          type: string
          example: '24 -TWENTY FOUR- 10周年記念コンプリートDVD-BOX'

    OrderReponse:
      description: '注文'
      allOf:
        - $ref: '#/components/schemas/OrderId'
        - $ref: '#/components/schemas/OrderModel'

    OrderRequest:
      description: '注文'
      allOf:
        - $ref: '#/components/schemas/OrderModel'

paths:
  /hello:
    get:
      tags:
        - hellos
      responses:
        '200':
          description: 登録されている支払い方法が返される。
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/responses/HelloResponse1"
                  - $ref: "#/components/responses/HelloResponse2"

              examples:
                response1:
                  summary: HelloResponse1の通常レスポンスです
                  value:
                    success1:
                      message_title: Response1
                      message: ハロー１のレスポンスのexampleです

                response2:
                  summary: HelloResponseの特別なレスポンスです
                  value:
                    success1:
                      message_title: Response２
                      message: ハロー２のレスポンスのexampleです

components:
  responses:
    HelloResponse1:
      type: object
      properties:
        success1:
          type: object
          properties:
            msg_title:
              type: string
              example: HelloResponse1
            message:
              type: string
              example: ハロー１のレスポンスです。

    HelloResponse2:
      type: object
      properties:
        success1:
          type: object
          properties:
            msg_title:
              type: string
              example: HelloResponse2
            message:
              type: string
              example: ハロー２のレスポンスです。