OpenAPI Specification からTypeScript型定義を生成するジェネレータ、swagger-to-tsを試す

GraphQLにおける graphql-codegen のような、 OpenAPI のSpecification から TypeScript の型定義を作ってくれる swagger-to-ts を触ってみました。

まとめ

VSCodeの補完が効いてうれしい
- typoやパラメータの不足などのミスを防ぐ

使い方

型定義ファイルの生成

Shipments.v1.yaml という OpenAPI 3.0 Specification から、Shipments.ts という TypeScriptを生成します。

OpenAPI 3.0 Specification は YAML でも JSON でも大丈夫です。

"scripts": {
    "generate:difinitions:shipments": "npx @manifoldco/swagger-to-ts Shipments.v1.yaml -o Shipments.ts"
  }

使用した OpenAPI 3.0 Specification

swagger: "2.0"
info:
  title: Shipments
  version: "1.0"
  description: ""
host: "localhost:3000"
schemes:
  - http
produces:
  - application/json
consumes:
  - application/json
paths:
  /addresses:
    get:
      summary: List all addresses
      tags:
        - Shipments
        - Addresses
      responses:
        "200":
          description: OK
          schema:
            type: object
            properties:
              next_token:
                type: string
                format: uuid
              addresses:
                type:
                  - string
                  - array
                items:
                  $ref: "#/definitions/Address"
              total:
                type: integer
          examples:
            example-1: {}
      operationId: get-addresses
      description: List all addresses
      parameters:
        - type: integer
          in: query
          name: limit
        - type: string
          in: query
          name: token
          format: uuid
          allowEmptyValue: false
    post:
      summary: Create a new address
      tags:
        - Shipments
        - Addresses
      operationId: post-addresses
      responses:
        "200":
          description: OK
          schema:
            $ref: "#/definitions/Address"
definitions:
  Address:
    title: Address
    type: object
    x-tags:
      - Addresses
      - Shipments
    x-examples:
      example-1: {}
    description: Delivery address
    properties:
      id:
        type: string
      country:
        type: string
        enum:
          - US
          - JP
        example: JP
        description: Country code
      state:
        type: string
      city:
        type: string
      street:
        type: string
      name:
        type: string
      company:
        type: string
      email:
        type: string
        format: email
      phone:
        type: string
        pattern: "[0-9]{10,11}"
    required:
      - country
      - state
      - city
      - street
      - name

生成された TypeScript 型定義

リクエストのパラメータなどはなく、definitions のみのようですね。

/**
 * This file was auto-generated by swagger-to-ts.
 * Do not make direct changes to the file.
 */

export interface definitions {
  /**
   * Delivery address
   */
  Address: {
    id?: string;
    /**
     * Country code
     */
    country: "US" | "JP";
    state: string;
    city: string;
    street: string;
    name: string;
    company?: string;
    email?: string;
    phone?: string;
  };
}

生成された TypeScript 型定義を使う

import * as Shipments from "../lib/Shipments";

const address: Shipments.definitions["Address"] = {
  country: "JP",
  state: "Saitama-ken",
  city: "Saitama Shi Omiya Ku",
  street: "Ginza Bld.7F, 1-5, Miyacho",
  name: "Yuichi Takeuchi",
};