Write Modes

Control which fields are accepted on create vs update

API Definition

config/apis/sharp_hawk.rb

# frozen_string_literal: true

Apiwork::API.define '/sharp_hawk' do
  key_format :camel

  export :openapi
  export :typescript
  export :zod

  resources :accounts
end

Models

app/models/sharp_hawk/account.rb

# frozen_string_literal: true

module SharpHawk
  class Account < ApplicationRecord
    validates :email, :name, presence: true
  end
end

Database Table

Column	Type	Default
id	string
created_at	datetime
email	string
name	string
role	string	member
updated_at	datetime
verified	boolean

Representations

app/representations/sharp_hawk/account_representation.rb

# frozen_string_literal: true

module SharpHawk
  class AccountRepresentation < Apiwork::Representation::Base
    attribute :id
    attribute :email, writable: :create
    attribute :name, writable: true
    attribute :role, writable: :update
    attribute :verified, writable: :update
    attribute :created_at
    attribute :updated_at
  end
end

Contracts

app/contracts/sharp_hawk/account_contract.rb

# frozen_string_literal: true

module SharpHawk
  class AccountContract < Apiwork::Contract::Base
    representation AccountRepresentation
  end
end

Controllers

app/controllers/sharp_hawk/accounts_controller.rb

# frozen_string_literal: true

module SharpHawk
  class AccountsController < ApplicationController
    before_action :set_account, only: %i[show update destroy]

    def index
      accounts = Account.all
      expose accounts
    end

    def show
      expose account
    end

    def create
      account = Account.create(contract.body[:account])
      expose account
    end

    def update
      account.update(contract.body[:account])
      expose account
    end

    def destroy
      account.destroy
      expose account
    end

    private

    attr_reader :account

    def set_account
      @account = Account.find(params[:id])
    end
  end
end

Request Examples

Create account

Request

http

POST /sharp_hawk/accounts
Content-Type: application/json

{
  "account": {
    "email": "alice@example.com",
    "name": "Alice Johnson"
  }
}

Response 201

json

{
  "account": {
    "id": "8324758d-5d34-504c-922a-694658537a93",
    "email": "alice@example.com",
    "name": "Alice Johnson",
    "role": "member",
    "verified": false,
    "createdAt": "2024-01-01T12:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:00.000Z"
  }
}

Update account

Request

http

PATCH /sharp_hawk/accounts/8324758d-5d34-504c-922a-694658537a93
Content-Type: application/json

{
  "account": {
    "name": "Alice Smith",
    "role": "admin",
    "verified": true
  }
}

Response 200

json

{
  "account": {
    "id": "8324758d-5d34-504c-922a-694658537a93",
    "email": "alice@example.com",
    "name": "Alice Smith",
    "role": "admin",
    "verified": true,
    "createdAt": "2024-01-01T12:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:00.000Z"
  }
}

Show account

Request

http

GET /sharp_hawk/accounts/8324758d-5d34-504c-922a-694658537a93

Response 200

json

{
  "account": {
    "id": "8324758d-5d34-504c-922a-694658537a93",
    "email": "alice@example.com",
    "name": "Alice Johnson",
    "role": "admin",
    "verified": true,
    "createdAt": "2024-01-01T12:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:00.000Z"
  }
}

Generated Output

Introspection

json

{
  "base_path": "/sharp_hawk",
  "enums": {
    "layer": {
      "deprecated": false,
      "description": null,
      "example": null,
      "values": [
        "http",
        "contract",
        "domain"
      ]
    }
  },
  "error_codes": {
    "unprocessable_entity": {
      "description": "Unprocessable Entity",
      "status": 422
    }
  },
  "info": null,
  "resources": {
    "accounts": {
      "actions": {
        "index": {
          "deprecated": false,
          "description": null,
          "method": "get",
          "operation_id": null,
          "path": "/accounts",
          "raises": [],
          "request": {
            "body": {},
            "query": {
              "page": {
                "default": null,
                "deprecated": false,
                "description": null,
                "example": null,
                "nullable": false,
                "optional": true,
                "type": "reference",
                "reference": "account_page"
              }
            }
          },
          "response": {
            "body": {
              "default": null,
              "deprecated": null,
              "description": null,
              "example": null,
              "nullable": null,
              "optional": null,
              "type": "union",
              "discriminator": null,
              "variants": [
                {
                  "default": null,
                  "deprecated": null,
                  "description": null,
                  "example": null,
                  "nullable": null,
                  "optional": null,
                  "type": "reference",
                  "reference": "account_index_success_response_body"
                },
                {
                  "default": null,
                  "deprecated": null,
                  "description": null,
                  "example": null,
                  "nullable": null,
                  "optional": null,
                  "type": "reference",
                  "reference": "error_response_body"
                }
              ]
            },
            "no_content": false
          },
          "summary": null,
          "tags": []
        },
        "show": {
          "deprecated": false,
          "description": null,
          "method": "get",
          "operation_id": null,
          "path": "/accounts/:id",
          "raises": [],
          "request": {
            "body": {},
            "query": {}
          },
          "response": {
            "body": {
              "default": null,
              "deprecated": null,
              "description": null,
              "example": null,
              "nullable": null,
              "optional": null,
              "type": "union",
              "discriminator": null,
              "variants": [
                {
                  "default": null,
                  "deprecated": null,
                  "description": null,
                  "example": null,
                  "nullable": null,
                  "optional": null,
                  "type": "reference",
                  "reference": "account_show_success_response_body"
                },
                {
                  "default": null,
                  "deprecated": null,
                  "description": null,
                  "example": null,
                  "nullable": null,
                  "optional": null,
                  "type": "reference",
                  "reference": "error_response_body"
                }
              ]
            },
            "no_content": false
          },
          "summary": null,
          "tags": []
        },
        "create": {
          "deprecated": false,
          "description": null,
          "method": "post",
          "operation_id": null,
          "path": "/accounts",
          "raises": [
            "unprocessable_entity"
          ],
          "request": {
            "body": {
              "account": {
                "default": null,
                "deprecated": false,
                "description": null,
                "example": null,
                "nullable": false,
                "optional": false,
                "type": "reference",
                "reference": "account_create_payload"
              }
            },
            "query": {}
          },
          "response": {
            "body": {
              "default": null,
              "deprecated": null,
              "description": null,
              "example": null,
              "nullable": null,
              "optional": null,
              "type": "union",
              "discriminator": null,
              "variants": [
                {
                  "default": null,
                  "deprecated": null,
                  "description": null,
                  "example": null,
                  "nullable": null,
                  "optional": null,
                  "type": "reference",
                  "reference": "account_create_success_response_body"
                },
                {
                  "default": null,
                  "deprecated": null,
                  "description": null,
                  "example": null,
                  "nullable": null,
                  "optional": null,
                  "type": "reference",
                  "reference": "error_response_body"
                }
              ]
            },
            "no_content": false
          },
          "summary": null,
          "tags": []
        },
        "update": {
          "deprecated": false,
          "description": null,
          "method": "patch",
          "operation_id": null,
          "path": "/accounts/:id",
          "raises": [
            "unprocessable_entity"
          ],
          "request": {
            "body": {
              "account": {
                "default": null,
                "deprecated": false,
                "description": null,
                "example": null,
                "nullable": false,
                "optional": false,
                "type": "reference",
                "reference": "account_update_payload"
              }
            },
            "query": {}
          },
          "response": {
            "body": {
              "default": null,
              "deprecated": null,
              "description": null,
              "example": null,
              "nullable": null,
              "optional": null,
              "type": "union",
              "discriminator": null,
              "variants": [
                {
                  "default": null,
                  "deprecated": null,
                  "description": null,
                  "example": null,
                  "nullable": null,
                  "optional": null,
                  "type": "reference",
                  "reference": "account_update_success_response_body"
                },
                {
                  "default": null,
                  "deprecated": null,
                  "description": null,
                  "example": null,
                  "nullable": null,
                  "optional": null,
                  "type": "reference",
                  "reference": "error_response_body"
                }
              ]
            },
            "no_content": false
          },
          "summary": null,
          "tags": []
        },
        "destroy": {
          "deprecated": false,
          "description": null,
          "method": "delete",
          "operation_id": null,
          "path": "/accounts/:id",
          "raises": [],
          "request": {
            "body": {},
            "query": {}
          },
          "response": {
            "body": {
              "default": null,
              "deprecated": null,
              "description": null,
              "example": null,
              "nullable": null,
              "optional": null,
              "type": null
            },
            "no_content": true
          },
          "summary": null,
          "tags": []
        }
      },
      "identifier": "accounts",
      "parent_identifiers": [],
      "path": "accounts",
      "resources": {}
    }
  },
  "types": {
    "account": {
      "deprecated": false,
      "description": null,
      "discriminator": null,
      "example": null,
      "extends": [],
      "shape": {
        "created_at": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "datetime"
        },
        "email": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "string",
          "format": null,
          "max": null,
          "min": null
        },
        "id": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "string",
          "format": null,
          "max": null,
          "min": null
        },
        "name": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "string",
          "format": null,
          "max": null,
          "min": null
        },
        "role": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "string",
          "format": null,
          "max": null,
          "min": null
        },
        "updated_at": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "datetime"
        },
        "verified": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "boolean"
        }
      },
      "type": "object",
      "variants": []
    },
    "account_create_payload": {
      "deprecated": false,
      "description": null,
      "discriminator": null,
      "example": null,
      "extends": [],
      "shape": {
        "email": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "string",
          "format": null,
          "max": null,
          "min": null
        },
        "name": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "string",
          "format": null,
          "max": null,
          "min": null
        }
      },
      "type": "object",
      "variants": []
    },
    "account_create_success_response_body": {
      "deprecated": false,
      "description": null,
      "discriminator": null,
      "example": null,
      "extends": [],
      "shape": {
        "account": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "reference",
          "reference": "account"
        },
        "meta": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": true,
          "type": "object",
          "partial": false,
          "shape": {}
        }
      },
      "type": "object",
      "variants": []
    },
    "account_index_success_response_body": {
      "deprecated": false,
      "description": null,
      "discriminator": null,
      "example": null,
      "extends": [],
      "shape": {
        "pagination": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "reference",
          "reference": "offset_pagination"
        },
        "accounts": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "array",
          "max": null,
          "min": null,
          "of": {
            "default": null,
            "deprecated": null,
            "description": null,
            "example": null,
            "nullable": null,
            "optional": null,
            "type": "reference",
            "reference": "account"
          },
          "shape": {}
        },
        "meta": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": true,
          "type": "object",
          "partial": false,
          "shape": {}
        }
      },
      "type": "object",
      "variants": []
    },
    "account_page": {
      "deprecated": false,
      "description": null,
      "discriminator": null,
      "example": null,
      "extends": [],
      "shape": {
        "number": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": true,
          "type": "integer",
          "format": null,
          "max": null,
          "min": 1
        },
        "size": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": true,
          "type": "integer",
          "format": null,
          "max": 100,
          "min": 1
        }
      },
      "type": "object",
      "variants": []
    },
    "account_show_success_response_body": {
      "deprecated": false,
      "description": null,
      "discriminator": null,
      "example": null,
      "extends": [],
      "shape": {
        "account": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "reference",
          "reference": "account"
        },
        "meta": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": true,
          "type": "object",
          "partial": false,
          "shape": {}
        }
      },
      "type": "object",
      "variants": []
    },
    "account_update_payload": {
      "deprecated": false,
      "description": null,
      "discriminator": null,
      "example": null,
      "extends": [],
      "shape": {
        "name": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": true,
          "type": "string",
          "format": null,
          "max": null,
          "min": null
        },
        "role": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": true,
          "type": "string",
          "format": null,
          "max": null,
          "min": null
        },
        "verified": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": true,
          "type": "boolean"
        }
      },
      "type": "object",
      "variants": []
    },
    "account_update_success_response_body": {
      "deprecated": false,
      "description": null,
      "discriminator": null,
      "example": null,
      "extends": [],
      "shape": {
        "account": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "reference",
          "reference": "account"
        },
        "meta": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": true,
          "type": "object",
          "partial": false,
          "shape": {}
        }
      },
      "type": "object",
      "variants": []
    },
    "error": {
      "deprecated": false,
      "description": null,
      "discriminator": null,
      "example": null,
      "extends": [],
      "shape": {
        "issues": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "array",
          "max": null,
          "min": null,
          "of": {
            "default": null,
            "deprecated": null,
            "description": null,
            "example": null,
            "nullable": null,
            "optional": null,
            "type": "reference",
            "reference": "issue"
          },
          "shape": {}
        },
        "layer": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "reference",
          "reference": "layer"
        }
      },
      "type": "object",
      "variants": []
    },
    "error_response_body": {
      "deprecated": false,
      "description": null,
      "discriminator": null,
      "example": null,
      "extends": [
        "error"
      ],
      "shape": {},
      "type": "object",
      "variants": []
    },
    "issue": {
      "deprecated": false,
      "description": null,
      "discriminator": null,
      "example": null,
      "extends": [],
      "shape": {
        "code": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "string",
          "format": null,
          "max": null,
          "min": null
        },
        "detail": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "string",
          "format": null,
          "max": null,
          "min": null
        },
        "meta": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "object",
          "partial": false,
          "shape": {}
        },
        "path": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "array",
          "max": null,
          "min": null,
          "of": {
            "default": null,
            "deprecated": null,
            "description": null,
            "example": null,
            "nullable": null,
            "optional": null,
            "type": "string",
            "format": null,
            "max": null,
            "min": null
          },
          "shape": {}
        },
        "pointer": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "string",
          "format": null,
          "max": null,
          "min": null
        }
      },
      "type": "object",
      "variants": []
    },
    "offset_pagination": {
      "deprecated": false,
      "description": null,
      "discriminator": null,
      "example": null,
      "extends": [],
      "shape": {
        "current": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "integer",
          "format": null,
          "max": null,
          "min": null
        },
        "items": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "integer",
          "format": null,
          "max": null,
          "min": null
        },
        "next": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": true,
          "optional": true,
          "type": "integer",
          "format": null,
          "max": null,
          "min": null
        },
        "prev": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": true,
          "optional": true,
          "type": "integer",
          "format": null,
          "max": null,
          "min": null
        },
        "total": {
          "default": null,
          "deprecated": false,
          "description": null,
          "example": null,
          "nullable": false,
          "optional": false,
          "type": "integer",
          "format": null,
          "max": null,
          "min": null
        }
      },
      "type": "object",
      "variants": []
    }
  }
}

TypeScript

export interface Account {
  createdAt: string;
  email: string;
  id: string;
  name: string;
  role: string;
  updatedAt: string;
  verified: boolean;
}

export interface AccountCreatePayload {
  email: string;
  name: string;
}

export interface AccountCreateSuccessResponseBody {
  account: Account;
  meta?: Record<string, unknown>;
}

export interface AccountIndexSuccessResponseBody {
  accounts: Account[];
  meta?: Record<string, unknown>;
  pagination: OffsetPagination;
}

export interface AccountPage {
  number?: number;
  size?: number;
}

export interface AccountShowSuccessResponseBody {
  account: Account;
  meta?: Record<string, unknown>;
}

export interface AccountUpdatePayload {
  name?: string;
  role?: string;
  verified?: boolean;
}

export interface AccountUpdateSuccessResponseBody {
  account: Account;
  meta?: Record<string, unknown>;
}

export interface AccountsCreateRequest {
  body: AccountsCreateRequestBody;
}

export interface AccountsCreateRequestBody {
  account: AccountCreatePayload;
}

export interface AccountsCreateResponse {
  body: AccountsCreateResponseBody;
}

export type AccountsCreateResponseBody = AccountCreateSuccessResponseBody | ErrorResponseBody;

export type AccountsDestroyResponse = never;

export interface AccountsIndexRequest {
  query: AccountsIndexRequestQuery;
}

export interface AccountsIndexRequestQuery {
  page?: AccountPage;
}

export interface AccountsIndexResponse {
  body: AccountsIndexResponseBody;
}

export type AccountsIndexResponseBody = AccountIndexSuccessResponseBody | ErrorResponseBody;

export interface AccountsShowResponse {
  body: AccountsShowResponseBody;
}

export type AccountsShowResponseBody = AccountShowSuccessResponseBody | ErrorResponseBody;

export interface AccountsUpdateRequest {
  body: AccountsUpdateRequestBody;
}

export interface AccountsUpdateRequestBody {
  account: AccountUpdatePayload;
}

export interface AccountsUpdateResponse {
  body: AccountsUpdateResponseBody;
}

export type AccountsUpdateResponseBody = AccountUpdateSuccessResponseBody | ErrorResponseBody;

export interface Error {
  issues: Issue[];
  layer: Layer;
}

export type ErrorResponseBody = Error;

export interface Issue {
  code: string;
  detail: string;
  meta: Record<string, unknown>;
  path: string[];
  pointer: string;
}

export type Layer = 'contract' | 'domain' | 'http';

export interface OffsetPagination {
  current: number;
  items: number;
  next?: null | number;
  prev?: null | number;
  total: number;
}

Zod

import { z } from 'zod';

export const LayerSchema = z.enum(['contract', 'domain', 'http']);

export const AccountSchema = z.object({
  createdAt: z.iso.datetime(),
  email: z.string(),
  id: z.string(),
  name: z.string(),
  role: z.string(),
  updatedAt: z.iso.datetime(),
  verified: z.boolean()
});

export const AccountCreatePayloadSchema = z.object({
  email: z.string(),
  name: z.string()
});

export const AccountPageSchema = z.object({
  number: z.number().int().min(1).optional(),
  size: z.number().int().min(1).max(100).optional()
});

export const AccountUpdatePayloadSchema = z.object({
  name: z.string().optional(),
  role: z.string().optional(),
  verified: z.boolean().optional()
});

export const IssueSchema = z.object({
  code: z.string(),
  detail: z.string(),
  meta: z.record(z.string(), z.unknown()),
  path: z.array(z.string()),
  pointer: z.string()
});

export const OffsetPaginationSchema = z.object({
  current: z.number().int(),
  items: z.number().int(),
  next: z.number().int().nullable().optional(),
  prev: z.number().int().nullable().optional(),
  total: z.number().int()
});

export const AccountCreateSuccessResponseBodySchema = z.object({
  account: AccountSchema,
  meta: z.record(z.string(), z.unknown()).optional()
});

export const AccountIndexSuccessResponseBodySchema = z.object({
  accounts: z.array(AccountSchema),
  meta: z.record(z.string(), z.unknown()).optional(),
  pagination: OffsetPaginationSchema
});

export const AccountShowSuccessResponseBodySchema = z.object({
  account: AccountSchema,
  meta: z.record(z.string(), z.unknown()).optional()
});

export const AccountUpdateSuccessResponseBodySchema = z.object({
  account: AccountSchema,
  meta: z.record(z.string(), z.unknown()).optional()
});

export const ErrorSchema = z.object({
  issues: z.array(IssueSchema),
  layer: LayerSchema
});

export const ErrorResponseBodySchema = ErrorSchema;

export const AccountsIndexRequestQuerySchema = z.object({
  page: AccountPageSchema.optional()
});

export const AccountsIndexRequestSchema = z.object({
  query: AccountsIndexRequestQuerySchema
});

export const AccountsIndexResponseBodySchema = z.union([AccountIndexSuccessResponseBodySchema, ErrorResponseBodySchema]);

export const AccountsIndexResponseSchema = z.object({
  body: AccountsIndexResponseBodySchema
});

export const AccountsShowResponseBodySchema = z.union([AccountShowSuccessResponseBodySchema, ErrorResponseBodySchema]);

export const AccountsShowResponseSchema = z.object({
  body: AccountsShowResponseBodySchema
});

export const AccountsCreateRequestBodySchema = z.object({
  account: AccountCreatePayloadSchema
});

export const AccountsCreateRequestSchema = z.object({
  body: AccountsCreateRequestBodySchema
});

export const AccountsCreateResponseBodySchema = z.union([AccountCreateSuccessResponseBodySchema, ErrorResponseBodySchema]);

export const AccountsCreateResponseSchema = z.object({
  body: AccountsCreateResponseBodySchema
});

export const AccountsUpdateRequestBodySchema = z.object({
  account: AccountUpdatePayloadSchema
});

export const AccountsUpdateRequestSchema = z.object({
  body: AccountsUpdateRequestBodySchema
});

export const AccountsUpdateResponseBodySchema = z.union([AccountUpdateSuccessResponseBodySchema, ErrorResponseBodySchema]);

export const AccountsUpdateResponseSchema = z.object({
  body: AccountsUpdateResponseBodySchema
});

export const AccountsDestroyResponseSchema = z.never();

export interface Account {
  createdAt: string;
  email: string;
  id: string;
  name: string;
  role: string;
  updatedAt: string;
  verified: boolean;
}

export interface AccountCreatePayload {
  email: string;
  name: string;
}

export interface AccountCreateSuccessResponseBody {
  account: Account;
  meta?: Record<string, unknown>;
}

export interface AccountIndexSuccessResponseBody {
  accounts: Account[];
  meta?: Record<string, unknown>;
  pagination: OffsetPagination;
}

export interface AccountPage {
  number?: number;
  size?: number;
}

export interface AccountShowSuccessResponseBody {
  account: Account;
  meta?: Record<string, unknown>;
}

export interface AccountUpdatePayload {
  name?: string;
  role?: string;
  verified?: boolean;
}

export interface AccountUpdateSuccessResponseBody {
  account: Account;
  meta?: Record<string, unknown>;
}

export interface AccountsCreateRequest {
  body: AccountsCreateRequestBody;
}

export interface AccountsCreateRequestBody {
  account: AccountCreatePayload;
}

export interface AccountsCreateResponse {
  body: AccountsCreateResponseBody;
}

export type AccountsCreateResponseBody = AccountCreateSuccessResponseBody | ErrorResponseBody;

export type AccountsDestroyResponse = never;

export interface AccountsIndexRequest {
  query: AccountsIndexRequestQuery;
}

export interface AccountsIndexRequestQuery {
  page?: AccountPage;
}

export interface AccountsIndexResponse {
  body: AccountsIndexResponseBody;
}

export type AccountsIndexResponseBody = AccountIndexSuccessResponseBody | ErrorResponseBody;

export interface AccountsShowResponse {
  body: AccountsShowResponseBody;
}

export type AccountsShowResponseBody = AccountShowSuccessResponseBody | ErrorResponseBody;

export interface AccountsUpdateRequest {
  body: AccountsUpdateRequestBody;
}

export interface AccountsUpdateRequestBody {
  account: AccountUpdatePayload;
}

export interface AccountsUpdateResponse {
  body: AccountsUpdateResponseBody;
}

export type AccountsUpdateResponseBody = AccountUpdateSuccessResponseBody | ErrorResponseBody;

export interface Error {
  issues: Issue[];
  layer: Layer;
}

export type ErrorResponseBody = Error;

export interface Issue {
  code: string;
  detail: string;
  meta: Record<string, unknown>;
  path: string[];
  pointer: string;
}

export type Layer = 'contract' | 'domain' | 'http';

export interface OffsetPagination {
  current: number;
  items: number;
  next?: null | number;
  prev?: null | number;
  total: number;
}

OpenAPI

yml

---
openapi: 3.1.0
info:
  title: "/sharp_hawk"
  version: 1.0.0
paths:
  "/accounts":
    get:
      operationId: accountsIndex
      parameters:
      - in: query
        name: page
        required: false
        schema:
          "$ref": "#/components/schemas/accountPage"
      responses:
        '200':
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/accountIndexSuccessResponseBody"
          description: Successful response
    post:
      operationId: accountsCreate
      requestBody:
        content:
          application/json:
            schema:
              properties:
                account:
                  "$ref": "#/components/schemas/accountCreatePayload"
              type: object
              required:
              - account
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/accountCreateSuccessResponseBody"
          description: Successful response
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/errorResponseBody"
  "/accounts/{id}":
    get:
      operationId: accountsShow
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/accountShowSuccessResponseBody"
          description: Successful response
    patch:
      operationId: accountsUpdate
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                account:
                  "$ref": "#/components/schemas/accountUpdatePayload"
              type: object
              required:
              - account
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/accountUpdateSuccessResponseBody"
          description: Successful response
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/errorResponseBody"
    delete:
      operationId: accountsDestroy
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No content
components:
  schemas:
    account:
      properties:
        createdAt:
          type: string
          format: date-time
        email:
          type: string
        id:
          type: string
        name:
          type: string
        role:
          type: string
        updatedAt:
          type: string
          format: date-time
        verified:
          type: boolean
      type: object
      required:
      - createdAt
      - email
      - id
      - name
      - role
      - updatedAt
      - verified
    accountCreatePayload:
      properties:
        email:
          type: string
        name:
          type: string
      type: object
      required:
      - email
      - name
    accountCreateSuccessResponseBody:
      properties:
        account:
          "$ref": "#/components/schemas/account"
        meta:
          properties: {}
          type: object
      type: object
      required:
      - account
    accountIndexSuccessResponseBody:
      properties:
        pagination:
          "$ref": "#/components/schemas/offsetPagination"
        accounts:
          items:
            "$ref": "#/components/schemas/account"
          type: array
        meta:
          properties: {}
          type: object
      type: object
      required:
      - pagination
      - accounts
    accountPage:
      properties:
        number:
          type: integer
          minimum: 1
        size:
          type: integer
          minimum: 1
          maximum: 100
      type: object
    accountShowSuccessResponseBody:
      properties:
        account:
          "$ref": "#/components/schemas/account"
        meta:
          properties: {}
          type: object
      type: object
      required:
      - account
    accountUpdatePayload:
      properties:
        name:
          type: string
        role:
          type: string
        verified:
          type: boolean
      type: object
    accountUpdateSuccessResponseBody:
      properties:
        account:
          "$ref": "#/components/schemas/account"
        meta:
          properties: {}
          type: object
      type: object
      required:
      - account
    error:
      properties:
        issues:
          items:
            "$ref": "#/components/schemas/issue"
          type: array
        layer:
          enum:
          - http
          - contract
          - domain
          type: string
      type: object
      required:
      - issues
      - layer
    errorResponseBody:
      "$ref": "#/components/schemas/error"
    issue:
      properties:
        code:
          type: string
        detail:
          type: string
        meta:
          properties: {}
          type: object
        path:
          items:
            type: string
          type: array
        pointer:
          type: string
      type: object
      required:
      - code
      - detail
      - meta
      - path
      - pointer
    offsetPagination:
      properties:
        current:
          type: integer
        items:
          type: integer
        next:
          type:
          - integer
          - 'null'
        prev:
          type:
          - integer
          - 'null'
        total:
          type: integer
      type: object
      required:
      - current
      - items
      - total

Write Modes ​

API Definition ​

Models ​

Representations ​

Contracts ​

Controllers ​

Request Examples ​

Generated Output ​

Write Modes

API Definition

Models

Representations

Contracts

Controllers

Request Examples

Generated Output