- 追加された行はこの色です。
- 削除された行はこの色です。
[[JHIPSTER一覧]]
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]
サンプルとして、以下のリクエストクラスがあって、ＤＢにも格納するし、ＡＰＩでも受け取りたいとします。
class Hoge {
private String param1;
private String param2;
}
*** swaggerエディタ [#j5e8f1e0]
swaggerエディタを使うと文法の確認をしながら、設計を進めることができます。
文法が決まっているので、プログラムを覚えるような感じです。
https://editor.swagger.io/
サンプルとして、ペットショップのAPIが用意されています。
このサンプルをにらめっこして、どこに値を入れたらいいのかを、推理していきます。
*** エンティティのクラス名 [#pa0b09f5]
まずは、エンティティのクラス名をどこにいれるか？についてですが、いれなくてもよさそうな項目は省くとすると、
これは、
tags:
name: "クラス名先頭小文字1"
description: "クラスの日本語の説明"
name: "クラス名先頭小文字2"
description: "クラスの日本語の説明"
です。
そのしたに
schemes:
- "https"
- "http"
paths:
を入れ、以下の中身を適宜置き換え、文法チェックは、swaggerのwebのエディタで行いながら、整えていくという感じですかね。
一旦、ひな形に全部入れておいてから、不要なものを削るほうが楽かもしれません
/クラス名先頭小文字1:
post:
tags:
- "クラス名先頭小文字1"
summary: "クラス名の追加についての簡単な説明"
description: "クラス名の追加についての詳細な説明"
operationId: "addクラス名"
consumes:
- "application/json"
- "application/xml"
produces:
- "application/xml"
- "application/json"
parameters:
- in: "パラメータ名"
name: "パラメータ名"
description: "クラス名 object that needs to be added to the store"
required: 必須ならtrue
schema:
$ref: "#/definitions/クラス名"
responses:
"405":
description: "Invalid input"
security:
- クラス名先頭小文字store_auth:
- "write:クラス名先頭小文字s"
- "read:クラス名先頭小文字s"
put:
tags:
- "クラス名小文字"
summary: "クラス名小文字の更新についての簡潔な説明"
description: "クラス名小文字の更新についての説明"
operationId: "updateクラス名"
consumes:
- "application/json"
- "application/xml"
produces:
- "application/xml"
- "application/json"
parameters:
- in: "パラメータ名"
name: "パラメータ名"
description: "パラメータ名の説明"
required: true
schema:
$ref: "#/definitions/クラス名"
responses:
"400":
description: "Invalid ID supplied"
"404":
description: "クラス名 not found"
"405":
description: "Validation exception"
security:
- クラス名先頭小文字store_auth:
- "write:クラス名先頭小文字s"
- "read:クラス名先頭小文字s"
/クラス名先頭小文字/findBy検索用パラメータ先頭大文字:
get:
tags:
- "クラス名先頭小文字"
summary: "クラス名の検索用パラメータについての簡潔な説明"
description: "クラス名の検索用パラメータについての詳しい説明"
operationId: "findクラス名sBy検索用パラメータ先頭大文字"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "Enum型検索用パラメータ"
in: "query"
description: "Enum型検索用パラメータの説明"
required: true
type: "array"
items:
type: "string"
enum:
- "Enum値1"
- "Enum値2"
- "Enum値3"
default: "available"
collectionFormat: "multi"
responses:
"200":
description: "successful operation"
schema:
type: "array"
items:
$ref: "#/definitions/クラス名"
"400":
description: "Invalid status value"
security:
- クラス名先頭小文字store_auth:
- "write:クラス名先頭小文字s"
- "read:クラス名先頭小文字s"
/クラス名先頭小文字/findByTags:
get:
tags:
- "クラス名先頭小文字"
summary: "Finds クラス名s by tagsについての簡潔な説明"
description: "Muliple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing."
operationId: "findクラス名sByTags"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "tags"
in: "query"
description: "Tags to filter by"
required: true
type: "array"
items:
type: "string"
collectionFormat: "multi"
responses:
"200":
description: "successful operation"
schema:
type: "array"
items:
$ref: "#/definitions/クラス名"
"400":
description: "Invalid tag value"
security:
- クラス名先頭小文字store_auth:
- "write:クラス名先頭小文字s"
- "read:クラス名先頭小文字s"
deprecated: true
/クラス名先頭小文字/{クラス名先頭小文字Id}:
get:
tags:
- "クラス名先頭小文字"
summary: "Find クラス名先頭小文字 by IDについての簡潔な説明"
description: "Returns a single クラス名先頭小文字"
operationId: "getクラス名ById"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "クラス名先頭小文字Id"
in: "path"
description: "ID of クラス名先頭小文字 to return"
required: true
type: "integer"
format: "int64"
responses:
"200":
description: "successful operation"
schema:
$ref: "#/definitions/クラス名"
"400":
description: "Invalid ID supplied"
"404":
description: "クラス名 not found"
security:
- api_key: []
post:
tags:
- "クラス名先頭小文字"
summary: "Updates a クラス名先頭小文字 in the store with form dataについての簡潔な説明"
description: ""
operationId: "updateクラス名WithForm"
consumes:
- "application/x-www-form-urlencoded"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "パラメータ１"
in: "path"
description: "パラメータ1の説明"
required: true
type: "integer"
format: "int64"
- name: "パラメータ2"
in: "formData"
description: "パラメータ2の説明"
required: false
type: "string"
- name: "パラメータ3"
in: "formData"
description: "パラメータ3の説明"
required: false
type: "string"
responses:
"405":
description: "Invalid input"
security:
- クラス名先頭小文字store_auth:
- "write:クラス名先頭小文字s"
- "read:クラス名先頭小文字s"
delete:
tags:
- "クラス名先頭小文字"
summary: "クラス名先頭小文字についての削除についての簡潔な説明"
description: "クラス名先頭小文字についての削除についての詳細な説明"
operationId: "deleteクラス名"
produces:
- "application/xml"
- "application/json"
parameters:
- name: "api_key"
in: "header"
required: false
type: "string"
- name: "クラス名先頭小文字Id"
in: "path"
description: "クラス名 id to delete"
required: true
type: "integer"
format: "int64"
responses:
"400":
description: "Invalid ID supplied"
"404":
description: "クラス名 not found"
security:
- クラス名先頭小文字store_auth:
- "write:クラス名先頭小文字s"
- "read:クラス名先頭小文字s"
/クラス名先頭小文字/{クラス名先頭小文字Id}/uploadImage:
post:
tags:
- "クラス名先頭小文字"
summary: "uploads an imageについての簡潔な説明"
description: ""
operationId: "uploadFile"
consumes:
- "multipart/form-data"
produces:
- "application/json"
parameters:
- name: "クラス名先頭小文字Id"
in: "path"
description: "ID of クラス名先頭小文字 to update"
required: true
type: "integer"
format: "int64"
- name: "additionalMetadata"
in: "formData"
description: "Additional data to pass to server"
required: false
type: "string"
- name: "file"
in: "formData"
description: "file to upload"
required: false
type: "file"
responses:
"200":
description: "successful operation"
schema:
$ref: "#/definitions/ApiResponse"
security:
- クラス名先頭小文字store_auth:
- "write:クラス名先頭小文字s"
- "read:クラス名先頭小文字s"
*** コツ [#s499ca3f]
近そうなメソッドをサンプルからチョイスして、値を書き換えるのがいいと思います。
** jhipsterのサイトのAPI生成解説 [#iac5b253]
https://www.jhipster.tech/doing-api-first-development/
です。
** ソースコード上でのAPI生成の設定箇所 [#e53ef39c]
OpenApiConfigurationクラスでSwaggerにしているような感じです。
