プログラムの・・・・話をしよう。
このシリーズ。全くと言っていいほど、プログラムの話はしていないんですよねぇ～というわけで、「プログラムの話をしようか。。。」とあいなります。
今回、SpringBootでServer APIスタブを生成し、ビルド。できれば稼動させてみたいと思います。場合によっては（僕の気力によっては）二回に分けるので頑張って行きましょう。
今回のスコープ
はい。いつものように。。スコープははい。この通り。。。長いな。。やっぱり二回に分けようかな。（早くも。。）
作業前提
作業前提です。
| No. | 前提事項 | 備考 |
|---|---|---|
| 1 | JDKがインストールされている | JDKのインストールを参照してインストールしてください |
| 2 | Visutal Studio Codeがインストールされている。 | インストールしてください |
| 3 | Mavenがインストールされている | Mavenインストールを参照してインストールしてください |
| 4 | swagger-codegen-cli-3.0.30.jarがインストールされている | Swagger Codegenのインストールを参照してインストールしてください |
| 5 | ワークスペースがGitHub(もしくはGitLab)管理下 | 資源管理を始めようの手順を実施している。 |
また、SwaggerGeneratorにやられた話 と SwaggerGeneratorにやられた話 Codegen実行偏も使います。
そもそもSwaggerって何よ
Open API Initiativeの定義するAPI仕様書の標準フォーマットです。多くのAPI/GWがサポートを唄っていてなかなか協力なサポートっぷりです。
もともとAPI利用者に向けて「齟齬なくAPIの呼び方を伝えるため」のフォーマットです。こんな経験したことある人なら、そのありがたさがわかるのではないでしょうか。
- 隣のプロジェクトがシステム間連携をAPIで呼び出しで実現したいと言い出した。出て来たI/F仕様書をみたらEXCEL！！！どのレベルに何を書けばいいのかわかんない！！Mapどうすんの？Listどうすんの？ヘッダは？？
- I/Fは渡すけど。呼べるのは3か月先。だって僕らの開発はそのころやっと結合テストだもん。君たち、そこから2か月で設計からテストまで終わらせて、同時リリースしてくれるよね。。（４なす案件）
まぁ、どっちも嫌な感じですが。いいですか？あるあるなんですよ。。すごいでしょ？
「哀しいけどこれ、あるあるなのよね？」と、中尉風にいってみます。あぁフラグが。。。
そもそも、多階層の木構造を定義できるJSONベースのAPIを表形式で表すことってムリげーです。そこでYAML/JSONを利用してI/F仕様を記載してお互いに取り交わそうというのがSwaggerです。
I/Fを取り交わすのでこんなことができます。
- クライアントからAPIを呼び出すための部品の自動生成
- Rest APIサーバのStub実装（3ヵ月後といわず今からでも開始可能)
今回は後者の機能を利用しようと思います。簡単に描くとこんな感じです。
Server Stubを自動生成する。
設定ファイルを作成する。
生成コードのパッケージを決めるための設定ファイルを作成します。
> echo ""> c:\dev\workspace\options.json
> code c:\dev\workspace\options.json
{
"basePackage":"com.qiita.api",
"configPackage":"com.qiita.api.config"
}
ここでは、com.qiita.apiとしていますが、ご自分の設計に合わせて自由な値を利用してください。
コード生成
> cd c:\dev\workspace
> java --add-opens=java.base/java.util=ALL-UNNAMED -jar C:\dev\tools\codegen\swagger-codegen-cli-3.0.30.jar generate -i apiDesign.yml -c options.json -l spring -o spring-server
各オプションの意味はServer stub generator HOWTOを参照してください。
--add-opensについてはSwagger Generatorにやられた話を参照してください。
ここでエラーが出る場合、swagger-codegenが壊れている可能性があります。Swagger Codegeをダウンロードして、c:\dev\tools\codegen\に格納してください
コンパイルのための作業
code C:\dev\workspace\spring-server\pom.xml
SwaggerGeneratorにやられた話を参照し、pom.xmlを適宜修正する。
変更分はこんな感じ
<build>
…
<plugins>
…
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.0.2</version>
</plugin>
…
</plugins>
…
</build>
<dependencies>
…
<!--jaxbのおかげでコンパイルが通らない問題 -->
<dependency>
<groupId>javax.activation</groupId>
<artifactId>javax.activation-api</artifactId>
<version>1.2.0</version>
</dependency>
<dependency>
<groupId>javax.xml.bind</groupId>
<artifactId>jaxb-api</artifactId>
<version>2.4.0-b180830.0359</version>
</dependency>
<dependency>
<groupId>com.sun.xml.bind</groupId>
<artifactId>jaxb-core</artifactId>
<version>2.3.0.1</version>
</dependency>
<dependency>
<groupId>com.sun.xml.bind</groupId>
<artifactId>jaxb-impl</artifactId>
<version>2.4.0-b180830.0438</version>
</dependency>
…
</dependencies>
…
では早速コンパイルしてみます。
> cd c:\dev\workspace\spring-server
> mvn clean package
spring-server> mvn clean package
[INFO] Scanning for projects...
[INFO]
[INFO] ---------------------< io.swagger:swagger-spring >----------------------
[INFO] Building swagger-spring 1.0.0
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- maven-clean-plugin:3.1.0:clean (default-clean) @ swagger-spring ---
[INFO] Deleting C:\dev\workspace\spring-server\target
[INFO]
[INFO] --- maven-resources-plugin:3.1.0:resources (default-resources) @ swagger-spring ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] Copying 1 resource
[INFO] Copying 0 resource
…
[INFO] --- spring-boot-maven-plugin:2.1.16.RELEASE:repackage (repackage) @ swagger-spring ---
[INFO] Replacing main artifact with repackaged archive
[INFO]
[INFO] --- spring-boot-maven-plugin:2.1.16.RELEASE:repackage (default) @ swagger-spring ---
[INFO] Replacing main artifact with repackaged archive
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.666 s
[INFO] Finished at: 2021-11-22T01:25:02+09:00
[INFO] ------------------------------------------------------------------------
正常にコンパイルできることを確認。では起動させてみましょう。
その前に驚かないでください。途中、こんな画面が出ると思います。Open JDKに対して、Firewallが8080番のポートの利用可否が設定されていないからです。適切に設定して、通信を許可してあげましょう。
> mvn spring-boot:run
c:\dev\workspace\spring-server> mvn spring-boot:run
[INFO] Scanning for projects...
[INFO]
～中略～
[INFO] --- spring-boot-maven-plugin:2.1.16.RELEASE:run (default-cli) @ swagger-spring ---
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v2.1.16.RELEASE)
2021-11-22 07:00:11.550 INFO 5544 --- [ main] com.qiita.api.Swagger2SpringBoot : Starting Swagger2SpringBoot on DESKTOP-O85C3T1 with PID 5544 (c:\dev\workspace\spring-server\target\classes started by shupe in c:\dev\workspace\spring-server)
～中略～
2021-11-22 07:00:12.954 INFO 5544 --- [ main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8080 (http) with context path '/v1'
2021-11-22 07:00:12.956 INFO 5544 --- [ main] com.qiita.api.Swagger2SpringBoot : Started Swagger2SpringBoot in 1.616 seconds (JVM running for 3.32
あれ？何も動かない‼！
とまってしまった‼！なんで？僕はなにもしてないのに‼！ 初めての時はみんなこんな感じです。大丈夫。落ち着いてください。詳細は後述しますが、お使いのブラウザを開いて、http://localhost:8080/v1/を開いてみてください。こんな画面を見ることができると思います。
作業を記録しよう
作成したものをgitリポジトリに登録します。
cd c:\dev\workspace
echo **/target/** >> .gitignore ★mvnはtarget配下に一次ファイルを保存する野で管理対象外としてマーク
git add *
git commit -m "api 生成してみたよ"
git push ★githubへ登録
おめでとうございます。
あなたはご自分の力で、WebAPIを作ることができました。今はまだ問い合わせに対して単純に応答を返すだけの仕掛けですが。少しずつ拡張していくことで、これからどんどんと楽しいものを作ることができます。次回は生成されたコードの内容を解説します。
あっさり起動します。こうやって「簡単に動く」状態ができるまでは死ぬほど苦労したものです。おじさんたちは「昔はなぁ～」とか言っちゃいますけど、裏に何が隠されていて、どういう動作をしているかをきちんと理解するためには時々有効なので、生暖かく聞きましょう。
免責事項
この資料は、本作業を行うために作成したものであり、本作業によって生じた損害については一切の責任を負いません。