Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
1
Help us understand the problem. What is going on with this article?
@InaLab

Spring Bootで実装したREST APIから一瞬でAPIドキュメントを生成

はじめに

SpringBoot初心者向けです。マイクロサービスの実装にSpringBootを使うケースは多いと思いますが、最近勉強し始めた初心者にとって、UIの無いサービス開発って何となく心理的なハードルが高かったりするのではないでしょうか。(ん?そんなことないよ、という方はスルーしてくださいww)

その心理的ハードルが何かというと、APIテストの前にサクッとうまく動くかテストしたいよね、という時にCurlでコマンドを打たなければならないということ。普段からCurlはよく使ってるよ、というケースを除けば、毎回それなりに長めのコマンドを書き方を思い出しながら(もしくは調べながら)タイプするのはとても面倒です。

そんな初心者にとって、その面倒な部分を一瞬で解消できるのがSwagger-uiです。APIドキュメントの作成ツールとしてはデファクトになりつつあると思っていますが、このSwagger-uiは、既に出来ているソースに数行追加するだけで、簡単に自動生成出来てしまいます。しかもこのSwagger-uiを使えば、GUIでAPIの簡単なテストも出来てしまいます。(実際には後ろでCurl叩いてくれている訳ですが)

という訳でSpringBootで作成したREST APIからSwagger-uiを生成するまでの流れをまとめておきます。(自分の備忘メモとして)

依存関係

Mavenを使っています。以下の依存関係をpom.xmlに追加します。

pom.xml

<pom>
    <repositories>
        <repository>
          <id>jcenter-snapshots</id>
          <name>jcenter</name>
          <url>https://jcenter.bintray.com/</url>
        </repository>
    </repositories>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
</pom>

今回は現時点(2020/10/13)で最新のSpringfox3.0.0を使用しています。3系へのバージョンアップで最低限必要なアノテーションの数も減りました。とりあえずサクッとという用途であれば、依存関係にこの設定を追加するだけでSwagger-uiは起動します。

Configに説明用のBeanを追加

依存関係の設定のみだとerror-basic-controllerが表示されてしまうので、それを除きたい場合は、以下のように@Configurationアノテーションを付けているConfigクラスに@Beanアノテーションを付けたDocketクラスを追加しておきます。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RestController;

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class MicroserviceConfig {

    @Bean
    public Docket customImplementation() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.any())
                .build();
    }
}

今回は省略していますが、上記DocketクラスではAPI内容の説明などの記載もできますので、その辺はまた興味があれば調べてみてください。

Swagger-uiを表示

これであとは、SpringBootを起動して http://localhost:8080/swagger-ui/ にアクセスすると以下の画面が表示されます。

image.png
あとはポチポチとGUIでJSONファイルの中身を編集して実行すれば、サクッと簡単な疎通確認は出来てしまいます。

おわりに

こんな簡単にできるなんて素晴らしいですね。Springfox3系は以前のバージョンよりも手間が減っているので、より導入のハードルは下がっていると思います。初心者の方には特におススメです。当記事が少しでも誰かの参考になれば幸いです。

1
Help us understand the problem. What is going on with this article?
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away

Comments

No comments
Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account Login
1
Help us understand the problem. What is going on with this article?