# 正しい例
parameters:
  - name: owner
    in: query
    required: true

# 間違った例（requestBodyは使用しない）
requestBody:
  content:
    application/json:
      schema:
        properties:
          owner:
            type: string

info:
  title: "MyToken Solidity Interface"
  version: "1.0.0"
  description: |
    MyToken コントラクトの Solidity インターフェイスを OpenAPI 形式で表現した仕様です。
    このコントラクトは以下のコントラクトを継承しています。

    ・ERC20
    ・Ownable
    ・Pausable

openapi: 3.0.3
info:
  title: "コントラクト名 Solidity Interface"
  version: "1.0.0"
  description: |
    コントラクトの説明。
    継承関係やネットワーク情報などをここに記載。

tags:
  - name: Read Functions
    description: Functions that retrieve information from the contract without modifying state.
  - name: Write Functions
    description: Functions that modify state.
  - name: Variables
  - name: Constants
  - name: Mapping
  - name: Events
  - name: Errors
  - name: Structs
  - name: Modifier

x-tagGroups:
  - name: Functions
    tags:
      - Read Functions
      - Write Functions
  - name: Storage
    tags:
      - Variables
      - Constants
      - Mapping
  - name: Others
    tags:
      - Events
      - Errors
      - Structs
      - Modifier

paths:
  # 関数、イベント、エラー、構造体のパス定義

components:
  schemas:
    # ErrorResponse、イベントスキーマ、構造体スキーマ

/totalSupply:
  get:
    summary: "totalSupply"
    description: |
      トークンの総供給量を返します。

      この関数はERC20標準で定義されており、現在発行されているトークンの総量を確認できます。
      ガス代は発生しません。
    operationId: totalSupply
    tags:
      - Read Functions
    responses:
      "200":
        description: "正常終了時のレスポンスです。"
        content:
          application/json:
            schema:
              type: object
              properties:
                result:
                  type: string
                  description: "トークンの総供給量（wei単位）。"
                  example: "1000000000000000000000000"

/balanceOf:
  get:
    summary: "balanceOf"
    description: |
      指定されたアカウントのトークン残高を取得します。

      ERC20標準関数です。この関数を呼び出すことで、任意のアドレスが保有しているトークンの量を確認できます。
      ブロックチェーンのステートを変更しないため、ガス代は発生しません。
    operationId: balanceOf
    tags:
      - Read Functions
    parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
        description: "所有者のアドレスを指定します。40桁の16進数文字列である必要があります。"
        example: "0x1234567890123456789012345678901234567890"
    responses:
      "200":
        description: "正常終了時のレスポンスです。"
        content:
          application/json:
            schema:
              type: object
              properties:
                result:
                  type: string
                  description: "指定されたアドレスのトークン残高（wei単位）を返します。"
                  example: "1000000000000000000"

/allowance:
  get:
    summary: "allowance"
    description: |
      `spender` が `owner` から使用を許可されているトークン量を取得します。

      ERC20標準関数です。この関数により、あるアドレス（`owner`）が別のアドレス（`spender`）に対して、
      どれだけのトークンを使用することを許可しているかを確認できます。
      `approve` 関数で設定された許可量が返されます。
    operationId: allowance
    tags:
      - Read Functions
    parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
        description: "トークンを所有しているアドレスを指定します。"
        example: "0x1234567890123456789012345678901234567890"
      - name: spender
        in: query
        required: true
        schema:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
        description: "トークンの使用を許可されたアドレスを指定します。"
        example: "0x0987654321098765432109876543210987654321"
    responses:
      "200":
        description: "正常終了時のレスポンスです。"
        content:
          application/json:
            schema:
              type: object
              properties:
                result:
                  type: string
                  description: "`spender` が使用できる残りのトークン量（wei単位）を返します。"
                  example: "500000000000000000"

/transfer:
  post:
    summary: "transfer"
    description: |
      指定されたアドレスにトークンを転送します。

      ERC20標準関数です。この関数を呼び出すと、呼び出し元のアカウントから `to` で指定したアドレスに、
      `amount` で指定した量のトークンが転送されます。

      トランザクションが成功すると、`Transfer` イベントが発行されます。
      残高が不足している場合や、送金先が無効なアドレスの場合はエラーが発生します。
    operationId: transfer
    tags:
      - Write Functions
    parameters:
      - name: to
        in: query
        required: true
        schema:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
        description: "送金先のアドレスを指定します。ゼロアドレス（`0x0000000000000000000000000000000000000000`）は指定できません。"
        example: "0x1234567890123456789012345678901234567890"
      - name: amount
        in: query
        required: true
        schema:
          type: string
        description: "トークン量を指定します（wei単位）。呼び出し元の残高以下である必要があります。"
        example: "1000000000000000000"
    responses:
      "200":
        description: "正常終了時のレスポンスです。"
        content:
          application/json:
            schema:
              type: object
              properties:
                result:
                  type: boolean
                  description: "送金が成功した場合 `true` を返します。"
                  example: true
      "500":
        description: "この関数で発生しうるエラーの一覧です。\n\n・InsufficientBalance\n\n・InvalidAddress"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ErrorResponse'
            examples:
              InsufficientBalance:
                summary: "残高不足"
                value:
                  message: "InsufficientBalance"
                  data: {}
              InvalidAddress:
                summary: "無効なアドレス"
                value:
                  message: "InvalidAddress"
                  data: {}

/transferFrom:
  post:
    summary: "transferFrom"
    description: |
      第三者が所有者の代わりにトークンを転送します。

      ERC20標準関数です。この関数は、`approve` 関数で事前に許可された量の範囲内で、
      `from` アドレスから `to` アドレスにトークンを転送します。

      呼び出し元は、`from` アドレスから十分な許可量（allowance）を得ている必要があります。
      転送が成功すると、`Transfer` イベントが発行され、許可量が減少します。
    operationId: transferFrom
    tags:
      - Write Functions
    parameters:
      - name: from
        in: query
        required: true
        schema:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
        description: "トークンの転送元アドレスを指定します。このアドレスから `amount` 分のトークンが引き出されます。"
        example: "0x1234567890123456789012345678901234567890"
      - name: to
        in: query
        required: true
        schema:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
        description: "トークンの転送先アドレスを指定します。ゼロアドレスは指定できません。"
        example: "0x0987654321098765432109876543210987654321"
      - name: amount
        in: query
        required: true
        schema:
          type: string
        description: "転送するトークン量を指定します（wei単位）。呼び出し元の許可量以下である必要があります。"
        example: "1000000000000000000"
    responses:
      "200":
        description: "正常終了時のレスポンスです。"
        content:
          application/json:
            schema:
              type: object
              properties:
                result:
                  type: boolean
                  description: "転送が成功した場合 `true` を返します。"
                  example: true
      "500":
        description: "この関数で発生しうるエラーの一覧です。\n\n・InsufficientBalance\n\n・InsufficientAllowance\n\n・InvalidSender\n\n・InvalidReceiver"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ErrorResponse'
            examples:
              InsufficientBalance:
                summary: "残高不足"
                value:
                  message: "InsufficientBalance"
                  data:
                    account: "0x1234567890123456789012345678901234567890"
                    balance: "500000000000000000"
                    required: "1000000000000000000"
              InsufficientAllowance:
                summary: "許可量不足"
                value:
                  message: "InsufficientAllowance"
                  data:
                    spender: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
                    allowance: "500000000000000000"
                    required: "1000000000000000000"
              InvalidSender:
                summary: "無効な送信者アドレス"
                value:
                  message: "InvalidSender"
                  data:
                    sender: "0x0000000000000000000000000000000000000000"
              InvalidReceiver:
                summary: "無効な受信者アドレス"
                value:
                  message: "InvalidReceiver"
                  data:
                    receiver: "0x0000000000000000000000000000000000000000"

components:
  schemas:
    ErrorResponse:
      type: object
      description: "コントラクト呼び出し時のエラー情報を表現する共通スキーマです。"
      properties:
        message:
          type: string
          description: "カスタムエラー名またはrevert/requireのメッセージ文字列。"
        data:
          type: object
          description: "追加情報（任意）。カスタムエラーが引数を持つ場合、その値をここに格納します。"

error InsufficientBalance(address account, uint256 balance, uint256 required);

{
  "account": "0x1234567890123456789012345678901234567890",
  "balance": "100",
  "required": "1000"
}

"500":
  description: "この関数で発生しうるエラーの一覧です。\n\n・InsufficientBalance\n\n・InvalidAddress\n\n・AmountZero"

"500":
  description: |
    この関数で発生しうるエラーの一覧です。

    ・InsufficientBalance
    ・InvalidAddress
    ・AmountZero
    ・Unauthorized
    ・ContractPaused

examples:
  InsufficientBalance:
    summary: "残高不足"
    value:
      message: "InsufficientBalance"
      data: {}
  InvalidAddress:
    summary: "無効なアドレス"
    value:
      message: "InvalidAddress"
      data:
        address: "0x0000000000000000000000000000000000000000"

examples:
  Unauthorized:
    summary: "権限がありません"
    value:
      message: "Unauthorized"
      data: {}

examples:
  InsufficientBalance:
    summary: "残高不足"
    value:
      message: "InsufficientBalance"
      data:
        account: "0x1234567890123456789012345678901234567890"
        balance: "500000000000000000"
        required: "1000000000000000000"
  InsufficientAllowance:
    summary: "許可量不足"
    value:
      message: "InsufficientAllowance"
      data:
        spender: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
        allowance: "100000000000000000"
        required: "500000000000000000"

examples:
  RequireError:
    summary: "require文によるエラー"
    value:
      message: "Amount must be greater than zero"
      data: {}

/events/Transfer:
  get:
    summary: "Transfer"
    description: |
      トークンが転送された時に発行されるイベントです。

      ERC20標準イベントです。このイベントは、`transfer` 関数や `transferFrom` 関数が実行されたときに発行されます。
      トークンの移動を追跡するために使用されます。

      **パラメータ:**
      - `from` (address) - indexed
      - `to` (address) - indexed
      - `value` (uint256)
    operationId: event_Transfer
    tags:
      - Events
    responses:
      "200":
        description: "トークン転送イベント"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferEvent'

components:
  schemas:
    TransferEvent:
      type: object
      description: "Transfer イベント。トークンが転送されたときに発行されます。"
      properties:
        from:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
          description: "indexed: true。送金元のアドレス。トピックとして検索可能です。"
          example: "0x1234567890123456789012345678901234567890"
        to:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
          description: "indexed: true。送金先のアドレス。トピックとして検索可能です。"
          example: "0x0987654321098765432109876543210987654321"
        value:
          type: string
          description: "indexed: false。転送されたトークン量（wei単位）。"
          example: "1000000000000000000"

/events/Approval:
  get:
    summary: "Approval"
    description: |
      トークンの使用許可が設定された時に発行されるイベントです。

      ERC20標準イベントです。このイベントは、`approve` 関数が実行されたときに発行されます。
      `owner` が `spender` に対してトークンの使用を許可した量を記録します。

      **パラメータ:**
      - `owner` (address) - indexed
      - `spender` (address) - indexed
      - `value` (uint256)
    operationId: event_Approval
    tags:
      - Events
    responses:
      "200":
        description: "承認イベント"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApprovalEvent'

components:
  schemas:
    ApprovalEvent:
      type: object
      description: "Approval イベント。トークンの使用許可が設定されたときに発行されます。"
      properties:
        owner:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
          description: "indexed: true。トークンの所有者アドレス。トピックとして検索可能です。"
          example: "0x1234567890123456789012345678901234567890"
        spender:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
          description: "indexed: true。トークンの使用を許可されたアドレス。トピックとして検索可能です。"
          example: "0x0987654321098765432109876543210987654321"
        value:
          type: string
          description: "indexed: false。許可されたトークン量（wei単位）。"
          example: "1000000000000000000"

/events/RoleGranted:
  get:
    summary: "RoleGranted"
    description: |
      ロールが付与された時に発行されるイベントです。

      AccessControl で使用されるイベントです。管理者が特定のアカウントに新しいロールを付与したときに発行されます。
      このイベントを監視することで、権限の変更履歴を追跡できます。

      **パラメータ:**
      - `role` (bytes32) - indexed
      - `account` (address) - indexed
      - `sender` (address) - indexed
    operationId: event_RoleGranted
    tags:
      - Events
    responses:
      "200":
        description: "ロール付与イベント"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleGrantedEvent'

components:
  schemas:
    RoleGrantedEvent:
      type: object
      description: "RoleGranted イベント。ロールが付与されたときに発行されます。"
      properties:
        role:
          type: string
          pattern: "^0x[0-9a-fA-F]{64}$"
          description: "indexed: true。付与されたロールのID（bytes32形式）。"
          example: "0x0000000000000000000000000000000000000000000000000000000000000000"
        account:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
          description: "indexed: true。ロールを付与されたアカウントのアドレス。"
          example: "0x1234567890123456789012345678901234567890"
        sender:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
          description: "indexed: true。ロールを付与した管理者のアドレス。"
          example: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"

description: "indexed: true。送金元のアドレス。トピックとして検索可能です。"

description: "indexed: false。転送されたトークン量（wei単位）。"

/errors/Unauthorized:
  get:
    summary: "Unauthorized"
    description: |
      権限がないアカウントが操作を実行しようとした時に返されるエラーです。

      このエラーは、アクセス制御で保護された関数を、権限を持たないアカウントが呼び出した場合に発生します。
      適切な権限（ロール）を付与してから、再度実行してください。
    operationId: error_Unauthorized
    tags:
      - Errors
    responses:
      "200":
        description: "権限エラー"
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "Unauthorized"

/errors/InsufficientBalance:
  get:
    summary: "InsufficientBalance"
    description: |
      残高が不足している時に返されるエラーです。

      このエラーは、トークン転送や支払いの際に、実行者の残高が必要な量に満たない場合に発生します。
      `balance` フィールドで現在の残高を、`required` フィールドで必要な残高を確認できます。

      **エラー引数:**
      - `account` (address) - 残高が不足しているアカウントのアドレス
      - `balance` (uint256) - 現在の残高
      - `required` (uint256) - 必要な残高
    operationId: error_InsufficientBalance
    tags:
      - Errors
    responses:
      "200":
        description: "残高不足エラー"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsufficientBalanceError'

components:
  schemas:
    InsufficientBalanceError:
      type: object
      description: "InsufficientBalance エラー。残高が不足している場合に返されます。"
      properties:
        account:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
          description: "残高が不足しているアカウントのアドレス。"
          example: "0x1234567890123456789012345678901234567890"
        balance:
          type: string
          description: "現在の残高（wei単位）。"
          example: "500000000000000000"
        required:
          type: string
          description: "必要な残高（wei単位）。"
          example: "1000000000000000000"

/errors/InvalidAddress:
  get:
    summary: "InvalidAddress"
    description: |
      無効なアドレスが指定された時に返されるエラーです。

      このエラーは、ゼロアドレス（`0x0000000000000000000000000000000000000000`）が指定された場合や、
      コントラクトのロジック上許可されないアドレスが指定された場合に発生します。

      **エラー引数:**
      - `addr` (address) - 無効と判定されたアドレス
    operationId: error_InvalidAddress
    tags:
      - Errors
    responses:
      "200":
        description: "無効なアドレスエラー"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvalidAddressError'

components:
  schemas:
    InvalidAddressError:
      type: object
      description: "InvalidAddress エラー。無効なアドレスが指定された場合に返されます。"
      properties:
        addr:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
          description: "無効と判定されたアドレス。"
          example: "0x0000000000000000000000000000000000000000"

/totalSupply:
  get:
    summary: "totalSupply"
    description: |
      ```solidity
      uint256 public totalSupply;
      ```

      トークンの総供給量を取得します。

      ERC20標準のステート変数です。この値は、トークンの発行（mint）や焼却（burn）によって変動します。
      現在発行されているトークンの総量を確認できます。
    operationId: totalSupply
    tags:
      - Variables
    responses:
      "200":
        description: "正常終了時のレスポンスです。"
        content:
          application/json:
            schema:
              type: object
              properties:
                result:
                  type: string
                  description: "トークンの総供給量（wei単位）を返します。"
                  example: "1000000000000000000000000"

/DECIMALS:
  get:
    summary: "DECIMALS"
    description: |
      ```solidity
      uint8 public constant DECIMALS = 18;
      ```

      トークンの小数点以下の桁数を表す定数です。

      この値は、トークンの表示や計算において重要な役割を果たします。
      例えば、`DECIMALS` が18の場合、1トークンは `1 * 10^18` wei として扱われます。
      ERC20標準では、通常18が使用されます（Etherと同じ）。

      この値はコンパイル時に確定し、変更できません。
    operationId: DECIMALS
    tags:
      - Constants
    responses:
      "200":
        description: "正常終了時のレスポンスです。"
        content:
          application/json:
            schema:
              type: object
              properties:
                result:
                  type: integer
                  minimum: 0
                  maximum: 255
                  description: "小数点以下の桁数を返します。"
                  example: 18

/owner:
  get:
    summary: "owner"
    description: |
      ```solidity
      address public immutable owner;
      ```

      コントラクトのオーナーアドレスを取得します。

      この値は、コントラクトのデプロイ時にコンストラクタで設定されます。
      デプロイ後は変更できません。
      オーナーは、コントラクトの管理機能（ミント、バーン、権限設定など）にアクセスできます。
    operationId: owner
    tags:
      - Variables
    responses:
      "200":
        description: "正常終了時のレスポンスです。"
        content:
          application/json:
            schema:
              type: object
              properties:
                result:
                  type: string
                  pattern: "^0x[0-9a-fA-F]{40}$"
                  description: "コントラクトのオーナーアドレスを返します。"
                  example: "0x1234567890123456789012345678901234567890"

/ADMIN_ROLE:
  get:
    summary: "ADMIN_ROLE"
    description: |
      ```solidity
      bytes32 public constant ADMIN_ROLE = keccak256("ADMIN_ROLE");
      ```

      管理者ロールを表す定数です。

      AccessControl で使用されるロール識別子です。
      このロールを持つアカウントは、コントラクトの管理機能にアクセスできます。
      `hasRole(ADMIN_ROLE, account)` で、特定のアカウントがこのロールを持っているかを確認できます。
    operationId: ADMIN_ROLE
    tags:
      - Constants
    responses:
      "200":
        description: "正常終了時のレスポンスです。"
        content:
          application/json:
            schema:
              type: object
              properties:
                result:
                  type: string
                  pattern: "^0x[0-9a-fA-F]{64}$"
                  description: "ロールIDを表すbytes32値を返します。"
                  example: "0xdf8b4c520ffe197c5343c6f5aec59570151ef9a492f2c624fd45ddde6135ec42"

/balanceOf:
  get:
    summary: "balanceOf"
    description: |
      ```solidity
      mapping(address account => uint256) public balanceOf;
      ```

      各アカウントのトークン残高を管理するMappingです。

      ERC20標準のMappingです。アカウントアドレスをキーとして、そのアカウントが保有するトークン量を取得できます。
      トークンの転送や発行、焼却によって残高が変動します。
    operationId: balanceOf
    tags:
      - Mapping
    parameters:
      - name: account
        in: query
        required: true
        schema:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
        description: "残高を照会するアカウントのアドレスを指定します。"
        example: "0x1234567890123456789012345678901234567890"
    responses:
      "200":
        description: "正常終了時のレスポンスです。"
        content:
          application/json:
            schema:
              type: object
              properties:
                result:
                  type: string
                  description: "指定されたアカウントのトークン残高（wei単位）を返します。"
                  example: "1000000000000000000"

/allowance:
  get:
    summary: "allowance"
    description: |
      ```solidity
      mapping(address owner => mapping(address spender => uint256)) public allowance;
      ```

      `spender` が `owner` から使用を許可されているトークン量を管理するMappingです。

      ERC20標準のMappingです。このMappingは、トークンの所有者（`owner`）が、
      別のアカウント（`spender`）に対して使用を許可したトークン量を記録します。

      `approve` 関数で許可量を設定し、`transferFrom` 関数で実際に使用されます。
      `transferFrom` が実行されると、この許可量が減少します。
    operationId: allowance
    tags:
      - Mapping
    parameters:
      - name: owner
        in: query
        required: true
        schema:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
        description: "トークンの所有者アドレスを指定します。"
        example: "0x1234567890123456789012345678901234567890"
      - name: spender
        in: query
        required: true
        schema:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
        description: "トークンの使用を許可されたアドレスを指定します。"
        example: "0x0987654321098765432109876543210987654321"
    responses:
      "200":
        description: "正常終了時のレスポンスです。"
        content:
          application/json:
            schema:
              type: object
              properties:
                result:
                  type: string
                  description: "`spender` が使用できる残りのトークン量（wei単位）を返します。"
                  example: "500000000000000000"

/hasRole:
  get:
    summary: "hasRole"
    description: |
      ```solidity
      mapping(bytes32 role => mapping(address account => bool)) public hasRole;
      ```

      特定のアカウントが特定のロールを持っているかを確認するMappingです。

      AccessControl で使用されるMappingです。ロールID（`role`）とアカウントアドレス（`account`）の
      組み合わせに対して、そのアカウントがそのロールを持っているかどうかをブール値で管理します。

      `grantRole` 関数でロールが付与され、`revokeRole` 関数で剥奪されます。
    operationId: hasRole
    tags:
      - Mapping
    parameters:
      - name: role
        in: query
        required: true
        schema:
          type: string
          pattern: "^0x[0-9a-fA-F]{64}$"
        description: "確認するロールのID（bytes32形式）を指定します。"
        example: "0xdf8b4c520ffe197c5343c6f5aec59570151ef9a492f2c624fd45ddde6135ec42"
      - name: account
        in: query
        required: true
        schema:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
        description: "確認するアカウントのアドレスを指定します。"
        example: "0x1234567890123456789012345678901234567890"
    responses:
      "200":
        description: "正常終了時のレスポンスです。"
        content:
          application/json:
            schema:
              type: object
              properties:
                result:
                  type: boolean
                  description: "アカウントがロールを持っている場合 `true`、持っていない場合 `false` を返します。"
                  example: true

/structs/TokenInfo:
  get:
    summary: "TokenInfo"
    description: |
      トークンの基本情報を保持する構造体です。

      この構造体は、トークンのメタデータ（名前、シンボル、decimals）を一つのデータ構造にまとめています。
      コントラクトの初期化時や設定変更時に使用されます。

      **フィールド:**
      - `name` (string) - トークンの名前
      - `symbol` (string) - トークンのシンボル
      - `decimals` (uint8) - トークンの小数点以下の桁数
    operationId: struct_TokenInfo
    tags:
      - Structs
    responses:
      "200":
        description: "TokenInfo構造体"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenInfoStruct'

components:
  schemas:
    TokenInfoStruct:
      type: object
      description: "TokenInfo 構造体。トークンの基本情報を保持します。"
      properties:
        name:
          type: string
          description: "トークンの名前。例: 'MyToken'。"
          example: "Example Token"
        symbol:
          type: string
          description: "トークンのシンボル。例: 'MTK'。通常は3-5文字の大文字。"
          example: "EXT"
        decimals:
          type: integer
          minimum: 0
          maximum: 255
          description: "トークンの小数点以下の桁数。通常は18。"
          example: 18

/structs/VestingSchedule:
  get:
    summary: "VestingSchedule"
    description: |
      トークンのベスティング（段階的権利確定）スケジュールを管理する構造体です。

      この構造体は、トークンの配布スケジュールを定義します。
      ベスティング期間中、受益者は時間の経過とともに徐々にトークンを受け取る権利を獲得します。

      **フィールド:**
      - `beneficiary` (address) - 受益者のアドレス
      - `start` (uint256) - ベスティング開始時刻（UNIXタイムスタンプ）
      - `cliff` (uint256) - クリフ期間（秒）。この期間中はトークンを受け取れない
      - `duration` (uint256) - ベスティング期間（秒）
      - `totalAmount` (uint256) - ベスティング対象のトークン総量
      - `releasedAmount` (uint256) - すでに引き出されたトークン量
    operationId: struct_VestingSchedule
    tags:
      - Structs
    responses:
      "200":
        description: "VestingSchedule構造体"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VestingScheduleStruct'

components:
  schemas:
    VestingScheduleStruct:
      type: object
      description: "VestingSchedule 構造体。トークンのベスティングスケジュールを定義します。"
      properties:
        beneficiary:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
          description: "受益者のアドレス。このアドレスがベスティングされたトークンを受け取ります。"
          example: "0x1234567890123456789012345678901234567890"
        start:
          type: string
          description: "ベスティング開始時刻（UNIXタイムスタンプ、秒単位）。"
          example: "1704067200"
        cliff:
          type: string
          description: "クリフ期間（秒）。開始からこの期間中はトークンを引き出せません。"
          example: "2592000"
        duration:
          type: string
          description: "ベスティング期間（秒）。この期間をかけてトークンが徐々に権利確定します。"
          example: "31536000"
        totalAmount:
          type: string
          description: "ベスティング対象のトークン総量（wei単位）。"
          example: "1000000000000000000000"
        releasedAmount:
          type: string
          description: "すでに引き出されたトークン量（wei単位）。"
          example: "500000000000000000000"

/structs/Proposal:
  get:
    summary: "Proposal"
    description: |
      ガバナンス提案を管理する構造体です。

      この構造体は、DAOの投票提案に関する情報を保持します。
      提案の内容、投票状況、実行ステートなどを一元管理します。

      **フィールド:**
      - `id` (uint256) - 提案のID
      - `proposer` (address) - 提案者のアドレス
      - `targets` (address[]) - 実行対象のコントラクトアドレスのリスト
      - `values` (uint256[]) - 各呼び出しで送信するEther量のリスト
      - `signatures` (string[]) - 各呼び出しの関数シグネチャのリスト
      - `calldatas` (bytes[]) - 各呼び出しのコールデータのリスト
      - `startBlock` (uint256) - 投票開始ブロック番号
      - `endBlock` (uint256) - 投票終了ブロック番号
      - `forVotes` (uint256) - 賛成票の総数
      - `againstVotes` (uint256) - 反対票の総数
      - `abstainVotes` (uint256) - 棄権票の総数
      - `executed` (bool) - 提案が実行済みかどうか
      - `canceled` (bool) - 提案がキャンセル済みかどうか
    operationId: struct_Proposal
    tags:
      - Structs
    responses:
      "200":
        description: "Proposal構造体"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProposalStruct'

/modifiers/onlyOwner:
  get:
    summary: "onlyOwner"
    description: |
      ```solidity
      modifier onlyOwner() {
          require(msg.sender == owner, "Not owner");
          _;
      }
      ```

      このmodifierは、関数の実行者がコントラクトのオーナーであることを確認します。

      関数の実行前に `msg.sender` がオーナーアドレスと一致するかをチェックします。
      オーナー以外が実行した場合は、「Not owner」というメッセージとともにrevertします。

      **使用例:**
      - `mint` 関数: トークンの発行
      - `burn` 関数: トークンの焼却
      - `transferOwnership` 関数: オーナー権限の移譲
    operationId: modifier_onlyOwner
    tags:
      - Modifier
    responses:
      "200":
        description: "onlyOwner modifier"
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "onlyOwner"

/modifiers/onlyRole:
  get:
    summary: "onlyRole"
    description: |
      ```solidity
      modifier onlyRole(bytes32 role) {
          require(hasRole(role, msg.sender), "AccessControl: account is missing role");
          _;
      }
      ```

      このmodifierは、関数の実行者が指定されたロールを持っているかを確認します。

      AccessControl で使用されるmodifierです。関数の実行前に、呼び出し元のアカウントが
      指定されたロール（`role`）を持っているかをチェックします。
      ロールを持っていない場合は、エラーメッセージとともにrevertします。

      **引数:**
      - `role` (bytes32) - 必要なロールのID

      **使用例:**
      - `grantRole` 関数: ロールの付与（`ADMIN_ROLE` が必要）
      - `revokeRole` 関数: ロールの剥奪（`ADMIN_ROLE` が必要）
    operationId: modifier_onlyRole
    tags:
      - Modifier
    responses:
      "200":
        description: "onlyRole modifier"
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "onlyRole"

/modifiers/whenNotPaused:
  get:
    summary: "whenNotPaused"
    description: |
      ```solidity
      modifier whenNotPaused() {
          require(!paused, "Pausable: paused");
          _;
      }
      ```

      このmodifierは、コントラクトが一時停止ステートでないことを確認します。

      Pausable パターンで使用されるmodifierです。関数の実行前に、コントラクトの `paused` フラグを
      チェックします。コントラクトが一時停止中（`paused == true`）の場合は、関数の実行を拒否します。

      **使用例:**
      - `transfer` 関数: 一時停止中は転送を禁止
      - `mint` 関数: 一時停止中は発行を禁止
      - `burn` 関数: 一時停止中は焼却を禁止

      **関連するModifier:**
      - `whenPaused`: 一時停止中のみ実行可能（一時停止解除のため）
    operationId: modifier_whenNotPaused
    tags:
      - Modifier
    responses:
      "200":
        description: "whenNotPaused modifier"
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "whenNotPaused"

/modifiers/nonReentrant:
  get:
    summary: "nonReentrant"
    description: |
      ```solidity
      modifier nonReentrant() {
          require(_status != _ENTERED, "ReentrancyGuard: reentrant call");
          _status = _ENTERED;
          _;
          _status = _NOT_ENTERED;
      }
      ```

      このmodifierは、再入攻撃を防ぐためのガードです。

      ReentrancyGuard パターンで使用されるmodifierです。関数の実行中に、同じ関数が再度呼び出されることを防ぎます。
      外部コントラクトを呼び出す関数や、Etherを送信する関数に適用することで、再入攻撃のリスクを軽減できます。

      **仕組み:**
      1. 関数の実行前に、`_status` が `_NOT_ENTERED` であることを確認
      2. `_status` を `_ENTERED` に設定
      3. 関数本体を実行
      4. 関数の実行後、`_status` を `_NOT_ENTERED` に戻す

      **使用例:**
      - `withdraw` 関数: Etherの引き出し
      - `claim` 関数: 報酬の受け取り
    operationId: modifier_nonReentrant
    tags:
      - Modifier
    responses:
      "200":
        description: "nonReentrant modifier"
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "nonReentrant"

/mint:
  post:
    summary: "mint"
    description: |
      新しいトークンを発行します。

      指定されたアドレス（`to`）に、指定された量（`amount`）のトークンを新規に発行します。
      総供給量（`totalSupply`）が増加し、`Transfer` イベントが発行されます。

      :::message
      **Modifier**: この関数は `onlyOwner` modifierにより保護されています。
      コントラクトのオーナーのみが実行可能です。
      :::
    operationId: mint
    tags:
      - Write Functions

/withdraw:
  post:
    summary: "withdraw"
    description: |
      コントラクトからEtherを引き出します。

      呼び出し元のアカウントが預けているEtherの全額を引き出します。
      残高が不足している場合はエラーが発生します。

      :::message
      **Modifiers**:
      - `whenNotPaused`: コントラクトが一時停止中でないことを確認
      - `nonReentrant`: 再入攻撃を防止
      :::
    operationId: withdraw
    tags:
      - Write Functions

schema:
  type: string
  pattern: "^0x[0-9a-fA-F]{40}$"
  description: "Ethereumアドレス（40桁の16進数文字列）"
  example: "0x1234567890123456789012345678901234567890"

schema:
  type: string
  description: "符号なし256ビット整数（wei単位）。JavaScriptの安全な整数範囲を超えるため文字列として扱います。"
  example: "1000000000000000000"

schema:
  type: integer
  minimum: 0
  maximum: 255
  description: "符号なし8ビット整数（0-255の範囲）"
  example: 18

schema:
  type: string
  pattern: "^0x[0-9a-fA-F]{64}$"
  description: "32バイトの固定長バイト列（64桁の16進数文字列）"
  example: "0xdf8b4c520ffe197c5343c6f5aec59570151ef9a492f2c624fd45ddde6135ec42"

schema:
  type: boolean
  description: "真偽値"
  example: true

schema:
  type: string
  description: "文字列"
  example: "Example Token"

schema:
  type: array
  items:
    type: string
    pattern: "^0x[0-9a-fA-F]{40}$"
  description: "アドレスの配列"
  example:
    - "0x1234567890123456789012345678901234567890"
    - "0x0987654321098765432109876543210987654321"

schema:
  type: array
  items:
    type: string
  description: "uint256の配列（各要素は文字列として表現）"
  example:
    - "1000000000000000000"
    - "2000000000000000000"

/complexFunction:
  post:
    summary: "complexFunction"
    description: "複数の型を扱う関数の例です。"
    parameters:
      - name: account
        in: query
        required: true
        schema:
          type: string
          pattern: "^0x[0-9a-fA-F]{40}$"
        description: "アドレス型のパラメータ"
      - name: amount
        in: query
        required: true
        schema:
          type: string
        description: "uint256型のパラメータ（文字列として扱う）"
      - name: decimals
        in: query
        required: true
        schema:
          type: integer
          minimum: 0
          maximum: 255
        description: "uint8型のパラメータ（数値として扱える）"
      - name: isActive
        in: query
        required: true
        schema:
          type: boolean
        description: "bool型のパラメータ"
      - name: roleId
        in: query
        required: true
        schema:
          type: string
          pattern: "^0x[0-9a-fA-F]{64}$"
        description: "bytes32型のパラメータ"