Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
Help us understand the problem. What is going on with this article?

OpenAPI(Swagger)導入下調べ

More than 1 year has passed since last update.

20190326161049.png

概要

前プロジェクト(新規開発)でOpenAPIを導入するために下調べしたときのまとめメモ。

OpenAPIとは

  • API仕様書(HTMLベース)を自動生成できる
  • クライアント側(iOSなど)で実装するAPI通信コードを自動生成できる
  • サーバー側のAPIインターフェース部分を自動生成できる
  • 仮データを返すようなモックサーバーを自動生成できる

上記のようなことを、API定義ファイルを1つ作ることで可能にするAPI仕様書規格。
以前はSwaggerという名前で運営されていたが、技術仕様3.0からOpenAPIという名称に変更された。

参考①:Qiita記事 OpenAPI (Swagger) 超入門
参考②:Web版Editor(仮データ付き): Swagger Editor

導入経緯

初期のクライアント(iOSアプリ)開発にあたり、サーバー構成やAPI設計等の作業と並行して動く必要があり、下記のようなことをしたく導入。

  • 現状の仕様(←未確定のものも含む)をいったん文書化して、サーバー開発側とコミュニケーションをとりたい
  • 上記仕様をクライアント開発にさくっと取り込みたい
  • 上記仕様に合わせたモックサーバーをさくっと立てたい

たどり着いた方法もろもろ

1,共有方法

Githubに、YAML形式の仕様ファイルを置き共有。

2,編集方法

Web版Editorを使って編集するのが手軽だが、編集作業のたびに仕様ファイルをインポート・エクスポートしなければいけないので微妙。

VisualStudio Codeに専用プラグインSwaggerViewerをインストールして対応。
インストール後、対象ファイルビュー内で[shift + alt + P]対象ファイル副クリック→PreviewSwagger でプレビュー画面起動。

3,iOSコード取り込み方法

3−1コード生成

OpenAPIのコード生成プログラムは2種類。

  • swagger-codegen: Swagger本家のコード生成プログラム。
  • openapi-generator: 上記プログラムの一部開発者が立ち上げたOSSなコード生成プログラム。

当初はswagger-codegenを使おうとしたものの、コンパイルエラーが出ないようテンプレートファイルを使う必要があり、メンテナンス上で難があったため、今回はopenapi-generatorを使って生成。
なお、RxSwiftも使いたかったため、同時にjson形式の設定ファイルも用意。

0,インストール

brew install openapi-generator

1,設定ファイル(config.json)を用意

最小限の項目
{
  // pod関連設定
  "podSource": "{ :git => \"https://github.com/shoichikuraoka/example_api.git\"}",
  "projectName": "ExampleAPI",
  "podHomepage": "https://github.com/shoichikuraoka/example_api",
  "podSummary": "API example",
  "podVersion": "0.0.1",

  // RxSwift的にAPIを使う場合は必要
  "responseAs": "RxSwift"
}

※何を設定できるかはopenapi-generator config-help -g swift4で参照可。

2,生成

openapi-generator -g swift4 -i 定義書.yaml -o 出力先/

3−2コード取り込み

API通信以外の実装のバージョン管理に影響を与えるのはよくないため、CocoaPods経由で外部ライブラリとして取り込む。

1,生成コードのpodspecファイルを編集

編集する項目
# プッシュ先のGitURLを指定(コード生成時に設定ファイルでも指定可)
s.source = { :git => "https://github.com/shoichikuraoka/example_api.git"}

# 依存ライブラリのバージョン指定を外す
s.dependency 'RxSwift'
s.dependency 'Alamofire'

2,生成コードをgithubリポジトリにプッシュ。

3,アプリ側のPodsファイルを編集

pod 'ExampleAPI', :git => 'https://github.com/shoichikuraoka/example_api.git'

4,取り込み

pod install

4,モックサーバー設定方法

4−1サーバープログラム立ち上げ

手軽さ重視でapisproutを使用。

0,インストール

Github: apisprout releasesから、ビルド済みファイル(apisprout-v1.3.0-mac.tar.xz)をダウンロード。
ダウンロードしたファイルを解凍して実行ファイル(apisprout)を生成。
実行ファイルを/usr/local/bin/配下に移動。

1,起動

apisprout 定義書.yaml

2,確認

http://localhost:8000/(get系APIパス)をブラウザに入れてみて動作確認。

(ボツ案)

  • swagger-codegenでサーバーコードを生成して起動する方法: 手軽じゃない。テストデータが自動で入らない。
  • openapi-generatorでサーバーコードを生成して起動する方法: 手軽じゃない。nodejsがOpenAPI3.0に未対応。

4−2モックデータの挿入

モデル定義の各プロパティにexampleが入っていれば、それらが入ったモックデータを自動でapisproutが返す。
カスタマイズしたモックデータを返したい場合(例:配列の中身を多めにしたい)は、下記手順でexampleを定義・挿入する。

1,モックデータオブジェクトを定義する

components/examples配下に定義する。

モックデータオブジェクトの定義
components:
  schemas:
    …(省略)…
  examples:
    kariExampleObject:
      value:
        name: Taro Yamada
        age: 54

2,APIレスポンスに挿入

対象APIのレスポンス部分に挿入する。

モックデータオブジェクトの挿入
paths:
  /kari:
    get:
      tags:
      - kari
      operationId: getKari
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Kari'
              examples:
                nandemoii_mojiretsu:
                  $ref: '#/components/examples/kariExampleObject'

ex,直で定義する方法

データオブジェクトが行数も少なく、再利用もしないのであれば下記のように直定義の方がよいかも。

モックデータオブジェクトの直定義
paths:
  /kari:
    get:
      tags:
      - kari
      operationId: getKari
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Kari'
              example:
                name: Taro Yamada
                age: 54

参考

備考

(特になし)

ShoichiKuraoka
車メーカー←フリーランス←SIer。フリーランスの頃はiOS系を主に担当。参加プロジェクト:業務用プレゼンApp、位置情報SDK、通貨App、動画配信App…etc
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away