はじめに
OpenAPIを触る機会があって
- API仕様書の作成
- API仕様書からコードの自動生成
を行ったのでその際にやったことを備忘録も兼ねてまとめます。
API仕様書の作成
API仕様書を作成するにあたってOpenAPIを使用します。
ただ実際動かすまでに以下のような側面があります。
- 環境構築が少し面倒
- 環境構築できるまでOpenAPIがどういったものかイメージしづらい
なので、
Swagger EditorのWeb版
が実際に触って動かせるのでオススメです。
コードの横にプレビュー表示してくれて、
かつ非同期で更新してくれるのでAPI仕様書はこれ見ながら作成しました。
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仕様書からコードの自動生成
の流れが分かるようになってたなら幸いです