[[JHIPSTER一覧]] #contents * JHipsterでAPIを定義書から作成 [#g6a1a603] jhipsterで、アプリの初期設定時の選択肢にでてくる API first development using OpenAPI-generator を詳しく見ていきたいと思います。これは、Swagger v2 と OpenAPI v3 の両方をサポートしてる、API生成についてとなります。 APIの最初の開発では、コードからドキュメントを生成する代わりに、最初に仕様を記述してからコードを生成する必要があります。 ** メリット [#x0e4669e] - 実装の前に、資料を用意できるので、レビュー資料として使える。 - モックを生成することができる - 確認用のサーバを用意しなくてもよくなる ** OpenAPI v3で設計したファイルの置き場所 [#cdfd1a7c] OpenAPI仕様ファイルは src/main/resources/swagger/api.yml に置きます。 - - *** 確認用のダミーなクラスとかAPIとかの設定 [#o68d1d01] vscodeで、swaggerのツールがあるので、それを入れるといいと思います。 サンプルとして、以下のリクエストクラスがあって、DBにも格納するし、APIでも受け取りたいとします。 class Hoge { private String param1; private String param2; } *** swaggerエディタ [#j5e8f1e0] *** ローカルでswagger deitorを使いたい場合 [#a2c984f4] git clone https://github.com/swagger-api/swagger-editor.git *** インストールなしでswagger deitorを使いたい場合 [#qc72ca15] https://editor.swagger.io/ *** 起動後に出てくるAPI定義書のサンプルをみて一言 [#c14cdf71] swaggerエディタを使うと文法の確認をしながら、設計を進めることができます。 文法が決まっているので、プログラムを覚えるような感じです。で、デフォルトで出てくるバージョンが古くてわかりづらいので、新しいバージョンのサンプルを持ってきたほうが良いです。 *** サンプルの仕様書の場所 [#t9a85291] https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v3.0 サンプルとして、ペットショップのAPIが用意されています。 このサンプルをにらめっこして、どこに値を入れたらいいのかを、推理していきます。 ファイルは、vscodeのswagger viewerプラグインで見るとよいです。 shift + Alt + P で ビューワーが起動します。いろいろ、プラグインいれちゃうと、それでひらかないかもしれないから、そんときは、shift+ctrl+pで、Preview Swagger でビューワを起動できます。 *** OpenAPIで使う型 [#r1e28ffc] * OpenAPIで使う型 [#r1e28ffc] クラスに相当するのが、openapiのdefinitionのようです。 ここには、実際に、PetShopのサンプルを見ながら、あてはめていきます。 でも、型がわかんないよ!となるとおもいますので、まずは、 OpenAPIで使う型は、簡単なバリデーションチェックも指定できるようになっているのですが、6種類ぐらいしかないので、string、number、integer、array、boolean、object すべて覚えておきましょう。 https://swagger.io/docs/specification/data-models/data-types/ *** 型には、formatが指定できる [#j7e724ab] 型の数少ないとおもいましたか?日付とかないですよね。実は、型には、オプションとして、formatを指定して、型の種類が少ないのを補っているのです。 integerだと、int32、int64 numberだと、float、double stringだと、なにもなし、byte、binary、date、date-time、email、hostname、ipv4、url、uuidがあります。 *** クラス図をopenapiのdefinitionに置き換える [#l76c077f] *** コツ [#s499ca3f] 近そうなメソッドをサンプルからチョイスして、値を書き換えるのがいいと思います。 ** jhipsterのサイトのAPI生成解説 [#iac5b253] https://www.jhipster.tech/doing-api-first-development/ です。 ** ソースコード上でのAPI生成の設定箇所 [#e53ef39c] OpenApiConfigurationクラスでSwaggerにしているような感じです。