JHIPSTER一覧

JHipsterで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のツールがあるので、それを入れるといいと思います。

サンプルとして、以下のリクエストクラスがあって、DBにも格納するし、APIでも受け取りたいとします。

class Hoge {
  private String param1;
  private String param2; 
}

swaggerエディタ

ローカルでswagger deitorを使いたい場合

git clone https://github.com/swagger-api/swagger-editor.git

インストールなしでswagger deitorを使いたい場合

https://editor.swagger.io/

起動後に出てくる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にしているような感じです。

トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2020-12-05 (土) 15:51:56 (135d)