最初にSwaggerを知ったのは「現場至上主義 Spring Boot2 徹底活用」という本です。しかしよくわからないので飛ばしていたので、今回はそこをやり直しました。

Swaggerについてよくわからないという人が、少しわかったになれるを目標にします。

ちなみにSwaggerはOpenAPI準拠ということで、API管理のデファクトスタンダードと呼ばれるほどらしいです。

Swaggerどうやる

yamlファイルで記述したAPI仕様に基づいて、SwaggerUIがAPI定義を表示してくれます。SwaggerUIではリクエストパラメータの詳細やContent-Type、戻値の確認などできます。そしてCodegenがAPI定義に基づいてサーバー側とクライアント側のコードを自動生成してくれます。

今回はサーバー側のコードを自動生成してSpringで起動します。クライアント側はPostmanで代用して試していきます。

いきなりSwaggerを試す

まずは以下のサイトにアクセスします

左側がyamlでAPI仕様を書くエディタです
右側がSwaggerUIです
画面上部のリンクのGenetateとあるのがCodegenです

左で書いた内容を元に、他のツールが機能する感じですね。つまり左側のyamlファイルさえ記述できればあとはなんとかなる！ということですが、yamlファイルは超シンプルにします。

まずはAPIの情報を定義します

openapi: 3.0.0
info:
  title: Item API
  description: Item API sample study
  version: 1.0.0

書いた内容で右側のUIが更新されます。これはItemAPIであることをyamlにて宣言しているだけです。

次にサーバー情報を追記しておきます

openapi: 3.0.0
info:
  title: Item API
  description: Item API sample study
  version: 1.0.0
servers:
  - url: http://volkruss.com
  - url: http://volkruss2.com

右側にServersというドロップダウンが表示されました。これがサーバーのアドレスを指定します。というのもSwaggerUIでは実際にリクエストを投げることができるのです。なのでちゃんとしたサーバーを指定すれば、実際のAPIの結果を受け取ることができます。

自分のローカルにSwagerUIを作っておけば、ローカルホストで動いてるアプリケーション挙動が確認できるということです。（今回はブラウザでSwaggerUIを試しているのでできません）

次はルーティング情報を定義します。ここが一番重要なポイントで、どのURLに対してどのアクションで、どんな結果を返すのかを定義しています。

少し長いですが、一部を除いてすぐに理解できると思います。

openapi: 3.0.0
info:
  title: Item API
  description: Item API sample study
  version: 1.0.0
servers:
  - url: http://volkruss.com
  - url: http://volkruss2.com
paths:
  /items:
    get:
      summary: Get Item
      description: get all item info
      responses:
        '200':
          description: get Json Items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Item"
                example: 
                  - id: 1
                    name: 洗剤
                  - id: 2
                    name: 柔軟剤

/itemsのGETアクションに関して定義しています
レスポンスがステータス200の時json形式で配列を返します
- 配列以外にもいろいろ書けます
- 配列の型はcomponentで定義します(これから書きます)
exampleはサンプルとして返す具体的な値を定義していますが、今回の場合はItemという型がidとnameという変数を持っている想定で書いています。

これで/itemsに対するAPI定義がされています。

こんな戻り値が返ってくるよとサンプルの内容も反映されているのがわかりますね。

しかし、これではエラーが残っているのと$refってなにという疑問も残ります

$refが参照失敗しているというのと、Itemsというのが解決できないというエラーで怒られています。

この$refではcomponentで定義した内容を参照します。今回のコードの場合はcomponentに対してItemを定義してあげる必要があります。

openapi: 3.0.0
info:
  title: Item API
  description: Item API sample study
  version: 1.0.0
servers:
  - url: http://volkruss.com
  - url: http://volkruss2.com
paths:
  /items:
    get:
      summary: Get Item
      description: get all item info
      responses:
        '200':
          description: get Json Items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Item"
                example: 
                  - id: 1
                    name: 洗剤
                  - id: 2
                    name: 柔軟剤
components:
  schemas:
    Item:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Itemはid(integer)とname(string)を持ったオブジェクトであることを定義しました。これでUIのほうでもエラーがなくなっています。

SpringApplicationとして動かす

このAPI定義に基づいてコードを自動生成します。

画面上部のGeneateServerからspringを選択するとzipファイルがダウンロードされます

解凍したファイルをstsなどでインポートします

まず依存関係を追加しておきます

<dependency>
    <groupId>jakarta.xml.bind</groupId>
    <artifactId>jakarta.xml.bind-api</artifactId>
    <version>2.3.2</version>
</dependency>

参考

参考

少し自動生成されたファイルを見てみます

まずはmodel/Item.javaです

public class Item   {
  @JsonProperty("id")
  private Integer id = null;

  @JsonProperty("name")
  private String name = null;

  public Item id(Integer id) {
    this.id = id;
    return this;
  }

componentで定義した内容が定義されているのがわかります。

次にapi/ItemsApi.javaです

@javax.annotation.Generated(value = "io.swagger.codegen.v3.generators.java.SpringCodegen", date = "2022-10-01T09:48:15.864Z[GMT]")
@Validated
public interface ItemsApi {

    @Operation(summary = "Get Item", description = "get all item info", tags={  })
    @ApiResponses(value = { 
        @ApiResponse(responseCode = "200", description = "get Json Items", content = @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = Item.class)))) })
    @RequestMapping(value = "/items",
        produces = { "application/json" }, 
        method = RequestMethod.GET)
    ResponseEntity<List<Item>> itemsGet();

}

/itemsに対してListのResponseEntityを返すというitemsGetメソッドが定義されたインターフェースになっていることがわかります。

次にこのクラスの実装クラスであるapi/ItemsApiController.javaを見てみます

@javax.annotation.Generated(value = "io.swagger.codegen.v3.generators.java.SpringCodegen", date = "2022-10-01T09:48:15.864Z[GMT]")
@RestController
public class ItemsApiController implements ItemsApi {

    private static final Logger log = LoggerFactory.getLogger(ItemsApiController.class);

    private final ObjectMapper objectMapper;

    private final HttpServletRequest request;

    @org.springframework.beans.factory.annotation.Autowired
    public ItemsApiController(ObjectMapper objectMapper, HttpServletRequest request) {
        this.objectMapper = objectMapper;
        this.request = request;
    }

    public ResponseEntity<List<Item>> itemsGet() {
        String accept = request.getHeader("Accept");
        if (accept != null && accept.contains("application/json")) {
            try {
                return new ResponseEntity<List<Item>>(objectMapper.readValue("[ {\n  \"id\" : 1,\n  \"name\" : \"洗剤\"\n}, {\n  \"id\" : 2,\n  \"name\" : \"柔軟剤\"\n} ]", List.class), HttpStatus.NOT_IMPLEMENTED);
            } catch (IOException e) {
                log.error("Couldn't serialize response for content type application/json", e);
                return new ResponseEntity<List<Item>>(HttpStatus.INTERNAL_SERVER_ERROR);
            }
        }

        return new ResponseEntity<List<Item>>(HttpStatus.NOT_IMPLEMENTED);
    }

}

オーバーライドしているitemsGetメソッドはObjectMapperを利用してItemクラスを生成して、ResponseEntityを返しているのがわかります。

しかし、これはステータスコードは501になっているのでOKの200に修正しておきます。

return new ResponseEntity&lt;List&lt;Item&gt;&gt;(objectMapper.readValue(&quot;[ {\n  \&quot;id\&quot; : 1,\n  \&quot;name\&quot; : \&quot;洗剤\&quot;\n}, {\n  \&quot;id\&quot; : 2,\n  \&quot;name\&quot; : \&quot;柔軟剤\&quot;\n} ]&quot;, List.class), HttpStatus.OK);

これでSpringBootAppとして実行します。

次にPostmanからリクエストを送信します

Acceptというkeyに対してapplication/jsonというValueを指定してSendします

ステータスコード200で、サンプルで定義したItemが取得できていることがわかりました。

これでなんとなくSwaggerがわかったかと思います。APIを定義してコードの自動生成までやってしまう化け物です。

他にもAPI定義書をドキュメントとして生成したり、Springではspringfoxを利用することでSwaggerと連携できたりします。

その辺はまた今度やっていきます。

Swaggerが少しわかったになれる記事