【OpenAPI】Railsのコードを自動生成してみた

はじめに

OpenAPIを使用したRailsコードの自動生成を行いました。
以下のことを行ったので備忘録も兼ねてまとめます。

• OpenAPIドキュメントを作成・環境構築
• OpenAPIドキュメントからRuby on Rails のソースコードを生成（OpenAPI generator）
• Rails用のテンプレートの追加（OpenAPI generator）

実行結果は以下の GitHubにあげてます。

OpenAPIドキュメントを作成・環境構築

① OpenAPI-railsフォルダを作成

※以降の作業はOpenAPI-railsフォルダ下で行います。

console

mkdir OpenAPI-rails

② OpenAPIドキュメントを作成（openapi.yaml）

console

type nul > openapi.yaml

ファイルの中身はSwagger EditorのWeb版から取得します。

③ Dockerで環境構築

Dockerfileとdocker-compose.ymlを以下の内容で配置してください。

Dockerfile

# ReDocCLI公式のDockerfileを使用
# https://github.com/Redocly/redoc/blob/master/cli/Dockerfile

FROM node:alpine

RUN npm install -g redoc-cli

WORKDIR /data
EXPOSE 8080

ENTRYPOINT ["redoc-cli"]
CMD []

docker-compose.yml

version: '3.8'
services:
  swagger-ui:
    image: swaggerapi/swagger-ui
    ports:
      - 8011:8080
    volumes:
      - ./openapi.yaml:/usr/share/nginx/html/openapi.yaml
    environment:
      API_URL: openapi.yaml
  redoc:
    image: redocly/redoc
    ports:
      - 8012:80
    volumes:
      - ./openapi.yaml:/usr/share/nginx/html/openapi.yaml
    environment:
      SPEC_URL: openapi.yaml
  redoc-cli:
    build: .
    volumes:
      - ./openapi:/data

④ dockerイメージをbuild＆UP

console

# dockerイメージをbuild
docker-compose build

# dockerイメージをup
docker-compose up -d

⑤ localhost:8011 or localhost:8012で確認

以下のように表示されれば成功です。

localhost:8011：Swagger

localhost:8012：Redoc

OpenAPIドキュメントからRuby on Rails のソースコードを生成（OpenAPI generator）

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

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

console

npm install @openapitools/openapi-generator-cli

②rails_codesフォルダを作成

このフォルダ下にRailsコードを自動生成していきます。

console

mkdir rails_codes

③以下のコマンドでRailsコードを自動生成

console

openapi-generator-cli generate -g ruby-on-rails -i openapi.yaml -o ./rails_codes

-g : 生成するコードの種類を指定（ジェネレータ一覧）
-i : yamlファイル/xmlファイルのOpenAPIドキュメント
-o : 自動生成されるコードの出力先を指定

④Railsコードの自動生成を確認

以下のようなメッセージが出て、

console

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

rails_codes下にRailsコードが生成されてたらOKです。

※実際に生成されたコードは下記であげてます。

Rails用のテンプレートの追加（OpenAPI generator）

自動生成されるコードはテンプレートを設置して、
適応したいテンプレートを指定することで生成コードをカスタマイズできます。

①rails用のテンプレートを取ってくる

公開されてるGitHubからruby-on-rails-serverフォルダを取得してきて、
OpenAPI-railsフォルダ下に配置します。

②テンプレートを指定してコード生成コマンドを実施

console

openapi-generator-cli generate -g ruby-on-rails -i openapi.yaml -o ./rails_codes -t ruby-on-rails-server

-t : 使用するテンプレートを指定

ruby-on-rails-serverフォルダに何も手を加えていない場合は、
デフォルトの時と同じコードが生成されます。
テンプレートをカスタマイズして生成コードが変わることを確認してみてください。

まとめ

今回OpenAPIを使用したRailsコードの自動生成の手順を備忘録も兼ねて書きました。
テンプレートのカスタマイズの部分は正直自分も理解がまだ足りてない部分があるので、
何か分かったら追加で記事を書こうと思います

参考

• Swagger EditorのWeb版
• 公式GitHubのREADME
• openapi-generatorリファレンス