Zenn
🚀

Flutterで使うAPI関連のDartコードをOpenApi Generatorで自動生成する

2022/06/14に公開
Flutter
Dart
tech

OpenAPI Generator を使ってDartコード(null safety対応)を自動生成のまとめ

Open API Generator とは

OpenAPI Generator とは、OpenAPI Spec を元に、APIクライアントライブラリ（SDK生成）、サーバースタブ、ドキュメント、設定を自動的に生成することができるツールのことです。
https://qiita.com/teinen_qiita/items/e440ca7b1b52ec918f1b
https://github.com/OpenAPITools/openapi-generator
簡単に言えばYAML→コードにすることができる

Installation

https://openapi-generator.tech/docs/installation/

jarを使う
null safety対応のdartコードを生成するには最低のバージョンは6.0.0

wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/6.0.0/openapi-generator-cli-6.0.0.jar -O openapi-generator-cli.jar

API定義のYamlを記述する

example.yaml
paths:
  # paths オブジェクト
  /users:
    # path item オブジェクト
    get: # GET
      # Operationオブジェクト
      tags:
        - users
      summary: Get all users.
      description: Returns an array of User model
      parameters: []
      responses: # レスポンス定義
        '200': # HTTP status
          description: A JSON array of User model
          content:
            application/json: # レスポンスの形式指定
              schema: 
                type: array
                items:
                  $ref: '#/components/schemas/User' # 参照するモデル
                example: # サンプルデータ
                  - id: 1
                    name: John Doe
                  - id: 2
                    name: Jane Doe
    post: # POST
      tags: 
        - users
      summary: Create a new User
      description: Create a new User
      parameters: []
      requestBody: # リクエストボディ
        description: user to create
        content:
          application/json:
            schema: # POSTするオブジェクト
              $ref: '#/components/schemas/User'
            example:
              id: 3
              name: Richard Roe
      responses:
        '201':
          description: CREATED
  /users/{userId}:
    get:
      tags:
        - users
      summary: Get user by ID.
      description: Returns a single User model
      parameters: # リクエストパラメータ
        - name: userId
          in: path # パラメータをパス内に含める
          description: user id
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A single User model
          content:
            application/json:
              schema: 
                type: object
                items:
                  $ref: '#/components/schemas/User'
                example:
                  id: 1
                  name: John Doe

Yamlの記述についてはSwagger Editorを使えばSyntaxを確認できます

$ java -jar openapi-generator-cli.jar validate -i example.yaml 
Validating spec (example.yaml)
No validation issues detected.

YamlからDartのコードを自動生成する

java -jar openapi-generator-cli.jar generate -i example.yaml -g dart -o build

同じフォルダの/build/lib/にDartのコードが生成される
configは-cオプションで指定することができます
テンプレートは-tオプションで指定することができます

java -jar openapi-generator-cli.jar -DbrowserClient=false -DapiTests=false -DmodelTests=false \
  generate -i example.yaml -g dart -t template -o build

templateのmustacheファイルをいじってたら、カスタムされたdartコードは生成できる
デフォルトのtemplate構成
https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator/src/main/resources/dart2

classの内容をカスタムしたいなら、native_class.mustacheを編集
https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/main/resources/dart2/serialization/native/native_class.mustache

Discussion