株式会社クラウドワークスでエンジニアをしている、小西です。おすすめのサウナはウェルビー栄です。
2022年ごろからOSS活動をする機会が増え、OSSの公開にもチャレンジしていたりするのでOSSをテーマに記事を書いてみようと思います。
この記事でやろうとしていること
経済産業省が提供しているgBizINFOのクライアントAPI生成し、オープンソース化することとRubyGemsにアップロードするところまでをゴールとします。
gBizINFOは法人番号や法人名から企業等の活動情報が検索できるプラットフォームで、法人番号公表サイトやEDINET、職場情報総合サイトと紐付けして情報を取得することができます。そのため、法人の住所やファイナンス情報、事業概要などの情報が一括で閲覧できるサービスとなっています。
クライアントAPIは、gBizINFOが公開しているAPI仕様を元に自動生成します。タイトル通り爆速に生成するため、実装はほとんどありません。また、ソースコードはGitHubで管理します。
この記事をおすすめできる方
誰にでもおすすめしたい記事ですが、特におすすめできる対象者を挙げてみます。
gemのベースを生成
まずは、gemのベースを生成するためbundle gem を実行します。
$ bundle gem gbizinfo
Creating gem 'gbizinfo'...
MIT License enabled in config
Code of conduct enabled in config
Changelog enabled in config
RuboCop enabled in config
Initializing git repo in /Users/uichi/projects/github/gbizinfo
hint: Using 'master' as the name for the initial branch. This default branch name
hint: is subject to change. To configure the initial branch name to use in all
hint: of your new repositories, which will suppress this warning, call:
hint:
hint: git config --global init.defaultBranch <name>
hint:
hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and
hint: 'development'. The just-created branch can be renamed via this command:
hint:
hint: git branch -m <name>
create gbizinfo/Gemfile
create gbizinfo/lib/gbizinfo.rb
create gbizinfo/lib/gbizinfo/version.rb
create gbizinfo/sig/gbizinfo.rbs
create gbizinfo/gbizinfo.gemspec
create gbizinfo/Rakefile
create gbizinfo/README.md
create gbizinfo/bin/console
create gbizinfo/bin/setup
create gbizinfo/.gitignore
create gbizinfo/.rspec
create gbizinfo/spec/spec_helper.rb
create gbizinfo/spec/gbizinfo_spec.rb
create gbizinfo/.github/workflows/main.yml
create gbizinfo/LICENSE.txt
create gbizinfo/CODE_OF_CONDUCT.md
create gbizinfo/CHANGELOG.md
create gbizinfo/.rubocop.yml
Gem 'gbizinfo' was successfully created. For more information on making a RubyGem visit https://bundler.io/guides/creating_gem.html
これで、gemライブラリのベースができました。 生成されたディレクトリ内がこのようになっていれば、問題なしです。
./
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── Gemfile
├── LICENSE.txt
├── README.md
├── Rakefile
├── bin
│ ├── console
│ └── setup
├── gbizinfo.gemspec
├── lib
│ ├── gbizinfo
│ │ └── version.rb
│ └── gbizinfo.rb
├── sig
│ └── gbizinfo.rbs
└── spec
├── gbizinfo_spec.rb
└── spec_helper.rb
GitHubにリポジトリを作る
開発を進めていく前に、New repositoryから新しくリポジトリを作成していきます。
リポジトリが作成できたら、先ほど生成したgemのベースをGitHubにアップロードします。
git remote add origin https://github.com/uichi/gbizinfo.git git branch -M main git commit -m 'gemのベースを生成' git push -u origin main
これでリポジトリの準備は完了です。
gBizINFOのAPIスキーマを準備
クライアントAPIを生成するうえで重要なポイントとなるのが、APIスキーマです。スキーマが生成の元となるため、gBizINFOが提供しているAPI仕様から取得します。
gBizINFOのAPI仕様はSwaggerで公開されており、Webで閲覧が可能となっています。
また、クライアントAPI生成時はスキーマがOpenAPIフォーマットでなければならないため、スキーマのフォーマット変換も作業していきます。
スキーマデータはhttps://info.gbiz.go.jp/hojin/v2/api-docs から確認ができますが、JSON形式なためSwagger EditorからOpenAPIフォーマットへ変換します。
JSONのスキーマデータをコピー
https://info.gbiz.go.jp/hojin/v2/api-docsを開くとこのような画面になります。
表示されているJSONをすべてコピーします。
Swagger EditorでOpenAPIフォーマットにする
JSON形式でもOpenAPIに対応することはできるのですが、コメントアウトができないことや{} をつける必要があるなど個人的に扱いづらさを感じるためYAML形式に変換します。JSONの方がいいという方は、そのままでも問題ありません。
Swagger Editorを開きます。 初期状態では、このような画面になっています。
画面左側の黒い部分は、エディターになっているため先ほどコピーしたJSONを貼り付けます。 既存で入っている設定は消して構いません。
貼り付け後、画面右側がこのようになりgBizINFOのAPIスキーマが読み込まれていることが分かります。
Swagger Editor上でYAMLとOpenAPIに変換ができます。まずはYAML形式へと変換します。 EditタブからConvert to YAMLを選択してください。
変換後、貼り付けしたJSONがYAMLへと変換されたことが分かります。
次に、Convert to OpenAPI 3.0.xを選択するとOpenAPIへと変換されます。
変換後はこのうようになります。
最後に、gbizinfoディレクトリ内にスキーマを設置します。
$ mkdir openapi $ touch openapi/root.yaml
設置場所はopenapi/root.yamlとします。
スキーマを追加できたところで、GitHubにアップロードしておきます。
$ git add openapi/root.yaml $ git commit -m 'OpenAPIスキーマの追加' $ git push origin main
APIクライアントの生成
いよいよ、APIクライアントを生成していきます。
生成にはopenapi-generatorというOpenAPIスキーマからクライアントAPIを生成できるツールを使います。
インストールは、GitHubのREADMEを参考にしてください。
https://github.com/OpenAPITools/openapi-generator
生成コマンドを実行してみます。
$ openapi-generator generate -i openapi/root.yaml -g ruby --git-repo-id=gbizinfo --git-user-id=uichi --additional-properties=gemName=gbizinfo --additional-properties=gemVersion=0.1.0
Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI).
| Error count: 1, Warning count: 1
Errors:
-components.schemas.Schema name HashMap«string,string» doesn't adhere to regular expression ^[a-zA-Z0-9\.\-_]+$
Warnings:
-components.schemas.Schema name HashMap«string,string» doesn't adhere to regular expression ^[a-zA-Z0-9\.\-_]+$
at org.openapitools.codegen.config.CodegenConfigurator.toContext(CodegenConfigurator.java:620)
at org.openapitools.codegen.config.CodegenConfigurator.toClientOptInput(CodegenConfigurator.java:647)
at org.openapitools.codegen.cmd.Generate.execute(Generate.java:479)
at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)
エラーが出て処理が中断してしまいました。おそらく、OpenAPIスキーマの構文が原因でエラーが発生していると考えられます。
--skip-validate-specを指定すると構文エラーを無視できるかもしれないよとメッセージが出ているので、試してみると無事に初期ファイルとクライアントAPIが生成されました。
ここで再びGitHubにアップロードしておきます。
$ git add . $ git commit -m 'openapi-generatorを使い初期ファイルとクライアントAPIを生成' $ git push origin main
gemspecを設定する
openapi-generator generatorを実行した際にgemspecが更新されますが、必要最低限の項目だけ更新されます。変更したい項目がある場合は、このタイミングで設定をしていきます。
s.name = "gbizinfo" s.version = Gbizinfo::VERSION s.platform = Gem::Platform::RUBY - s.authors = ["OpenAPI-Generator"] - s.email = [""] - s.homepage = "https://openapi-generator.tech" + s.authors = ["uichi"] + s.email = ["37263474+uichi@users.noreply.github.com"] + s.homepage = "https://github.com/uichi/gbizinfo" s.summary = "gBizINFO REST API Ruby Gem" - s.description = "<div>各REST APIはHTTPリクエストヘッダX-hojinInfo-api-tokenに動作確認用のAPIトークンDTcLxzo1lZaUYaQPVdSRxdS4MzlXNCs4を指定して動作を確認することができます。</div><div>※動作確認用のAPIトークンはこのページでの動作確認でのみ使用してください。</div><div>※REST APIを利用する際は必ず、<a href='https://info.gbiz.go.jp/hojin/api_registration/form'>Web API利用申請</a>を行い、APIトークンを取得してください。</div>" - s.license = "Unlicense" + s.description = "経済産業省が提供するgBizInfoのRuby製クライアントAPI" + s.license = "MIT" s.required_ruby_version = ">= 2.7" s.add_runtime_dependency 'typhoeus', '~> 1.0', '>= 1.0.1'
ローカルでAPIリクエストを実行してみる
法人の基本情報を取得するエンドポイントに対して、試しにリクエストしてみます。 ローカルで実行するためには、gemをビルドしインストールする必要があります。
$ rake build gbizinfo 0.1.0 built to pkg/gbizinfo-0.1.0.gem $ bundle install
インストールできたところで、irbからリクエスト実行してみます。
$ irb require 'gbizinfo' api_instance = Gbizinfo::GBizINFORESTAPIApi.new x_hojin_info_api_token = 'xxxxxxxxxxxxxxxxxxxxx' corporate_number = '6010401098453' result = api_instance.get_certification_using_get(x_hojin_info_api_token, corporate_number)
result の中身を見てみると、こちらのようになっています。
#<Gbizinfo::HojinInfoResponse:0x0000000108c465e0
@hojin_infos=
[#<Gbizinfo::HojinInfo:0x0000000108c46e78
@capital_stock=2697177000,
@certification=[],
@corporate_number="6010401098453",
@employee_number=305,
@kana="くらうどわーくす",
@location="東京都渋谷区恵比寿４丁目２０番３号",
@name="株式会社クラウドワークス",
@postal_code="1500013",
@representative_name="代表取締役社長 吉田 浩一郎",
@status="-",
@update_date="2023-04-27T00:00:00+09:00">],
@id="6010401098453",
@message="200 - OK.">
問題なくクライアントAPIを使ってデータを取得できました。
以上でAPIクライアントの生成が完結しました！
GitHubでリリースしてみる
ソースコードの準備が整ったところで、こちらの記事を参考にGitHubからリリースしてみます。
Choose a tagからタグを作成します。 タグの設定をすると、Generate release notesボタンが押せるようになるのでクリックします。
リリースが整ったところで、Publish releaseを押してリリースします。 ちなみに、Set as a pre-releaseにチェックを入れておくとプレリリースとして公開できます。
以上でリリースができました！
RubyGemsに公開してみる
お待ちかねの、RubyGemsへのリリースをします。
リリースの対象となるのは、先ほどrake buildした際に生成されたpkg/gbizinfo-0.1.0.gem です。
下記を実行し実際にリリースしてみます。
$ rake release gbizinfo 0.1.0 built to pkg/gbizinfo-0.1.0.gem. Tag v0.1.0 has already been created. Pushing gem to https://rubygems.org... Successfully registered gem: gbizinfo (0.1.0) Pushed gbizinfo 0.1.0 to rubygems.org
公開されたページを見てみると、、
無事にリリースされました！
これで gem install からgbizinfoをインストールすることができます！🤟🏻
