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とかの設定 †

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

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

swaggerエディタ †

swaggerエディタを使うと文法の確認をしながら、設計を進めることができます。

文法が決まっているので、プログラムを覚えるような感じです。

https://editor.swagger.io/

サンプルとして、ペットショップのAPIが用意されています。

このサンプルをにらめっこして、どこに値を入れたらいいのかを、推理していきます。

↑

エンティティのクラス名 †

まずは、エンティティのクラス名をどこにいれるか？についてですが、いれなくてもよさそうな項目は省くとすると、

これは、

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"
↑

コツ †

近そうなメソッドをサンプルからチョイスして、値を書き換えるのがいいと思います。

↑

jhipsterのサイトのAPI生成解説 †

https://www.jhipster.tech/doing-api-first-development/

です。

↑

ソースコード上でのAPI生成の設定箇所 †

OpenApiConfiguration?クラスでSwaggerにしているような感じです。

トップ   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS