jhipsterで、アプリの初期設定時の選択肢にでてくる
API first development using OpenAPI-generator
を詳しく見ていきたいと思います。これは、Swagger v2 と OpenAPI v3 の両方をサポートしてる、API生成についてとなります。
APIの最初の開発では、コードからドキュメントを生成する代わりに、最初に仕様を記述してからコードを生成する必要があります。
OpenAPI仕様ファイルは
src/main/resources/swagger/api.yml
に置きます。
サンプルとして、以下のリクエストクラスがあって、DBにも格納するし、APIでも受け取りたいとします。
class Hoge { private String param1; private String param2; }
swaggerエディタを使うと文法の確認をしながら、設計を進めることができます。
文法が決まっているので、プログラムを覚えるような感じです。
サンプルとして、ペットショップの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: "パラメータ1" 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"
近そうなメソッドをサンプルからチョイスして、値を書き換えるのがいいと思います。
https://www.jhipster.tech/doing-api-first-development/
です。
OpenApiConfiguration?クラスでSwaggerにしているような感じです。