はじめに

OpenAPIを触る機会があって

API仕様書の作成
API仕様書からコードの自動生成

を行ったのでその際にやったことを備忘録も兼ねてまとめます。

API仕様書の作成

API仕様書を作成するにあたってOpenAPIを使用します。
ただ実際動かすまでに以下のような側面があります。

環境構築が少し面倒
環境構築できるまでOpenAPIがどういったものかイメージしづらい

なので、
Swagger EditorのWeb版
が実際に触って動かせるのでオススメです。

コードの横にプレビュー表示してくれて、
かつ非同期で更新してくれるのでAPI仕様書はこれ見ながら作成しました。

openapi.yml

swagger: '2.0'
info:
  description: >-
    This is a sample server Petstore server.  You can find out more about    
    Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net,
    #swagger](http://swagger.io/irc/).      For this sample, you can use the api
    key `special-key` to test the authorization     filters.
  version: 1.0.0
  title: Swagger Petstore
  termsOfService: http://swagger.io/terms/
  contact:
    email: apiteam@swagger.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
host: petstore.swagger.io
basePath: /v2
tags:
  - name: pet
    description: Everything about your Pets
    ...略

API仕様書からコードの自動生成

API仕様書からコードの自動生成を行うにはOpenAPIGeneratorを使用しました。

OpenAPIGeneratorを使用する方法は、いくつかありますが今回はnpmを使用しました。
（公式GitHubのREADMEで使用方法の一覧と方法が乗ってます）

※npmで使用する場合、JVMが必要だったのでJava 17をインストールしてます。

①npmでopenapi-generatorをインストールします

npm install @openapitools/openapi-generator-cli

②以下のような感じでコードを自動生成します

openapi-generator-cli generate -g <ジェネレーター> -i <生成元ファイル> -o <生成先のフォルダ>

-g : 生成するコードの種類を指定（ジェネレータ一覧）
-i :「API仕様書の作成」で使用したyamlファイル/xmlファイルを指定
-o : 自動生成されるコードの出力先を指定

③オプションでコードの自動生成をカスタマイズ

使用頻度高そうなオプションをピックアップして紹介します。

1. --global-propertyオプション

自動生成するコード群を指定たり、逆に生成しないコードを指定することもできます。
global-property一覧で指定できるプロパティを一覧で見れます。

# 実際こんな感じ
openapi-generator-cli generate -g <hoge> -i <hoge> -o <hoge> --global-property models
openapi-generator-cli generate -g <hoge> -i <hoge> -o <hoge> --global-property=apiDocs=false,modelDocs=false,...

2. -s, --skip-overwriteオプション

既存で同じファイルがある場合はそのファイルは上書きをしないオプションです。
こちらでgenerate時に指定できるoptionを一覧で見れます。

# 実際こんな感じ
openapi-generator-cli generate -g <hoge> -i <hoge> -o <hoge> --skip-overwrite

まとめ

今回API仕様書の作成からコードの自動生成までの手順を半分備忘録で書きました。

API仕様書の作成
API仕様書からコードの自動生成

の流れが分かるようになってたなら幸いです

参考