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