openapi2aspida in hey Tech Internship 2022

hey Tech Internship 2022 | エンジニア向けインターンシップ (opens new window)

I participated in the hey Tech Internship 2022 (hey, Inc.) on 9/5-16.

The internship program was a two-week development hackathon. My team consisted of two members: I was in charge of FrontEnd and the other was in charge of BackEnd.

The following technologies were used in this development.

- Vite/Vue.js 3.x(TypeScript)
- APIClient: openapi2aspida
- Store: pinia
- Formatter: prettier
- Linter: ESLint
- UI Component: Element Plus
- GitHooks: husky
- Test: Vitest
- other: qrcode, jsqr, html2canvas

What should be noted here is the use of openapi2aspida. This library is called aspida, which automatically creates a TypeScript friendly HTTP client from a Swagger file.

openapi2aspida

openapi2aspida is used as follows.

Swagger

Place swagger.yaml wherever you like.

swagger.yaml sample

openapi: 3.0.3
info:
  title: sample api - OpenAPI 3.0
  version: 1.0.11
paths:
  /products:
    post:
      summary: 商品を登録する
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/OnlineProducts"
      responses:
        "201":
          description: created products
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OnlineProducts"
    get:
      summary: 商品の一覧取得する
      responses:
        "200":
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/OnlineProducts"
components:
  schemas:
    OnlineProducts:
      type: object
      allOf:
        - "$ref": "#/components/schemas/Products"
        - properties:
            online_stock:
              type: object
              properties:
                sold_quantity:
                  description: 売れた商品の数量
                  type: integer
                stock_quantity:
                  description: 商品の在庫数
                  type: integer
                delivered_quantity:
                  description: 商品の在庫数
                  type: integer
    Products:
      type: object
      description: 登録された商品
      properties:
        id:
          type: integer
          description: 商品のID
        name:
          type: string
          description: 商品の名前
        price:
          type: integer
          description: 商品の値段
        image_url:
          type: string
          description: 商品画像
      required:
        - name
        - address
        - phone_number
        - mail_address
        - is_acceptance
        - online_stock

commands

Now enter the following command

$ SWAGGER_PATH = "swagger.yaml";
$ GENERATED_DIR = "src/lib";
$ npx openapi2aspida -i=${SWAGGER_PATH} -o=${GENERATED_DIR}

Then, APIClient will be created under src/lib as specified in GENERATED_DIR.

Typesafe request to API using aspida

Put the following in src/repos/index.ts

import axios from "axios";
import aspida from "@aspida/axios";
import api from "../lib/$api";

export const apiClient = api(
  aspida(axios, { baseURL: import.meta.env.VITE_MOCK_API_BASE_URL })
);

Use this to write the API request process as below:

const allProducts = (await apiClient.products.get()).body;
// allProducts is OnlineProducts[] type

---

You can put swagger.yaml anywhere you like according to your architecture. As for lib, when executing openapi2aspida in this example, the output result is as follows because src/lib is specified, but you can specify any location you like.

 README.md
 package.json
 ...
 src
 ├── swagger.yaml
 ├── lib // A client is automatically generated here as follows
 │   ├── @types
 │   ├── products
 │   ├── $api.ts
 │   └── index.ts
 ├── components
 │   └── hoge.vue
 └── App.vue

Among the files generated under lib, you will basically only see them in the @type directory.

Thus, with Swagger and Aspida, we can develop a method of making requests to the REST API that can withstand scale. I would like to thank the people at hey, Inc. and the members of my internship for giving me the opportunity to try out these skills.

reference

aspida/packages/aspida/docs/ja at main · aspida/aspida (opens new window)

Tweet