FlutterにOpenApiを入れて、api開発を楽にしよう。

openapi: 3.0.0
info:
  title: API
  description: Openapiのサンプル
  version: v1

servers:
  - url: http://localhost:8085/ # docker-composeでprismをホストしているポートと同じするものにする(後述)
paths:
  /users:
    $ref: "./resources/path/users.yml"
  /users/{id}: #{}で囲んだ場所は動的なパラメーターになります(後述)
    $ref: "./resources/path/user.yml"

ok:
  type: object
  required:
    - message
  properties:
    message:
      type: string
      example: 作成しました
    errorDetails:
      type: array
      items:
        $ref: '#/components/schemas/error_detail'
created:
  type: object
  required:
    - message
  properties:
    message:
      $ref: '#/components/schemas/message'
    errorDetails:
      type: array
      items:
        $ref: '#/components/schemas/error_detail'
bad_request:
  type: object
  required:
    - message
  properties:
    message:
      type: string
      example: BadRequest
    errorDetails:
      type: array
      items:
        $ref: '#/components/schemas/error_detail'
unauthorized:
  type: object
  required:
    - error
  properties:
    error:
      type: string
      example: 認証されていません
forbidden:
  type: object
  required:
    - message
  properties:
    message:
      type: string
      example: Forbidden
not_found:
  type: object
  required:
    - message
  properties:
    message:
      type: string
      example: Not Found
unprocessable_entity_error:
  type: object
  required:
    - message
  properties:
    message:
      type: string
      example: Unprocessable Entity
    errorDetails:
      type: array
      items:
        $ref: '#/components/schemas/error_detail'
internal_server_error:
  type: object
  required:
    - message
  properties:
    message:
      type: string
      example: Internal Server Error

components:
  schemas:
    error_detail:
      type: object
      required:
        - propertyName
        - propertyMessage
      properties:
        propertyName:
          type: string
          description: エラーになったプロパティ
          example: name
        propertyMessage:
          type: string
          description: エラーメッセージ
          example: 入力値が不正です。

get:
  summary: すべてのユーザーを取得する
  operationId: getUsers
  tags:
    - users
  responses:
    "200":
      description: "Ok"
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "../components/schemas/user.yml#/user"
    "401":
      description: "Unauthorized"
      content:
        application/json:
          schema:
            $ref: "../components/schemas/responses.yml#/unauthorized"
    "403":
      description: "Forbidden"
      content:
        application/json:
          schema:
            $ref: "../components/schemas/responses.yml#/forbidden"
    "404":
      description: "Not Found"
      content:
        application/json:
          schema:
            $ref: "../components/schemas/responses.yml#/not_found"
    "500":
      description: "Internal Server Error"
      content:
        application/json:
          schema:
            $ref: "../components/schemas/responses.yml#/internal_server_error"

post:
  summary: 新しいユーザーを追加する
  operationId: addUser
  tags:
    - users
  requestBody:
    description: ユーザー作成の引数
    content:
      application/json:
        schema:
          $ref: "../components/schemas/user.yml#/user"
  responses:
    "201":
      description: CREATED

summary → 該当処理の説明
operationId → OpenApi内で呼び出すためのUID(これがFlutter内部で呼び出すメソッド名になります)
tags → APIで使用されるタグ
responses →  該当処理で発生しうるレスポンスのステータスとその内容
requestBody → apiリクエスト時に送ることができるパラメーター

user: # ここに記載した命名が、型名になる(別ファイル等で重複した場合は、User1のように連番になる)
  type: object
  required:
    - name
    - email
    - gender
    - paymentPrice
    - familyCount
    - createdAt
  properties:
    name:
      type: string
      example: 山田 太郎
      description: ユーザーのフルネーム
    email:
      type: string
      example: [email protected]
      description: ユーザーのメールアドレス
    gender:
      type: string
      enum: [man, woman]
      example: man
      description: 性別
    address:
      type: string
      example: 東京都新宿区
      description: 住所
    familyCount:
      type: integer
      minimum: 1
      maximum: 20
      example: 1
      description: 自分を含む家族の人数
    createdAt:
      type: string
      format: date-time
      description: 作成日

get:
  summary: idに紐づくuserを取得する
  operationId: getUser
  tags:
    - users
  parameters:
    - in: path # パラメータをパス内に含める
      name: id
      description: ユーザーのID
      required: true
      schema:
        type: string
  responses:
    "200":
      description: Ok
      content:
        application/json:
          schema:
            $ref: "../components/schemas/user.yml#/user"
(中略)

- in: query
  name: name
  required: false # 必須ならtrueにする
  schema:
    type: string
    description: 検索対象の名前

version: '3.7'
services:
  app-frontend-sample-swagger-ui:
    image: swaggerapi/swagger-ui
    container_name: app-frontend-sample-swagger-ui
    volumes:
      - ./openapi.yml:/usr/share/nginx/html/openapi.yml
      - ./resources:/usr/share/nginx/html/resources
    environment:
      API_URL: openapi.yml
    ports:
      - "8080:8080"
  app-frontend-sample-swagger-api:
    image: stoplight/prism:3
    container_name: app-frontend-sample-swagger-api
    ports:
      - "8082:4010" # B.で作成したファイルのsurversのポートを左側に記載
    command: mock -d -h 0.0.0.0 /openapi.yml
    volumes:
      - ./generated/openapi/openapi.yaml:/openapi.yml
  app-frontend-sample-openapi-generator:
    image: openapitools/openapi-generator-cli
    container_name: app-frontend-sample-openapi-generator
    volumes:
      - ./:/workspace

################################################################################
# Thanks for using OpenAPI Generator.                                          #
# Please consider donation to help us maintain this project 🙏                 #
# https://opencollective.com/openapi_generator/donate                          #
################################################################################

dependencies:
  flutter:
    sdk: flutter
  (中略)
  openapi:
    path: ./openapi/client # openapiで生成したプロジェクトのパスを記載

import 'dart:io';

import 'package:dio/dio.dart';
import 'package:flutter/foundation.dart';
import 'package:openapi/openapi.dart';

class OpenApiFactory {
  OpenApiFactory();

  Openapi build() {
    const flavor = String.fromEnvironment('FLAVOR');
    final String baseUrl;
    bool isAndroid = Platform.isAndroid;
    if (flavor == 'prod') {
      baseUrl = ENV['BASE_URL'];
    } else if (flavor == 'stg') {
      baseUrl = isAndroid ? 'http://10.0.2.2:3000' : 'http://localhost:3000';
    } else {
      baseUrl = isAndroid ? 'http://10.0.2.2:8082' : 'http://localhost:8082';
    }
    return Openapi(
      basePathOverride: baseUrl,
      interceptors: [
        if (kDebugMode) LogInterceptor(requestBody: true, responseBody: true),
      ],
    );
  }
}

dev: モックサーバーのURL
stg: ローカルの開発中サーバーのURL
prod: 本番で運用するサーバーのURL

import 'package:flutter/material.dart';
import 'package:flutter_hooks/flutter_hooks.dart';
import 'package:front/config/const/theme_word.dart';
import 'package:front/domain/openapi_factory.dart';
import 'package:openapi/openapi.dart';

class TopPage extends HookWidget {
  const TopPage({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    final users = useState<List<User>>([]); #Openapiで定義したスキーマが、そのまま型として利用可能

    void getApiUsers() async {
      final Openapi _openApi = OpenApiFactory().build();
      final repository = _openApi.getUsersApi();
      final response = (await repository.getUsers());
      users.value = response.data!.toList();
    }

    return Scaffold(
        appBar: AppBar(
          title: const Text(ThemeWord.top),
        ),
        body: Column(children: users.value.map((user) => Text(user.name)).toList()),
        floatingActionButton: FloatingActionButton(onPressed: () => getApiUsers()));
  }
}

environment:
  sdk: ">=2.12.0 <3.0.0"