daisuzz.log

Spring Boot アプリケーションにSwaggerを導入する方法

今回は、Spring Bootで作成したRESTful API サーバアプリケーションに、Swaggerを導入してWebドキュメントを作成してみようと思います。

Swaggerとは

swagger.io

Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.

Swaggerとは、APIに関する、設計、ドキュメント、テストやデプロイまでをサポートしているフレームワークです。 Swaggerを使うことで、コードの雛形を自動生成することができたり、既存アプリケーションのドキュメントを自動生成することができます。 タイトルにもある通り、今回は既存アプリケーションのドキュメントを自動生成してみようと思います。

環境

  • Java 8
  • maven 3.5.3
  • Spring Boot 1.5.10
  • springfox-swagger2 2.7.0
  • springfox-swagger-ui 2.7.0

ドキュメントを導入するAPIサーバのControllerのコードは以下のものです。 Swaggerによってこの仕様を反映したドキュメントが生成されます。

@RestController
public class SampleWebController {

    private final SampleUserRepository sampleUserRepository;

    @Autowired
    SampleWebController(SampleUserRepository sampleUserRepository) {
        this.sampleUserRepository = sampleUserRepository;
    }

    @GetMapping("/users")
    public List<User> getUsers() {
        return sampleUserRepository.getUsers();
    }

    @GetMapping("/user/{userId}")
    public User getUser(@PathVariable Integer userId) {
        return sampleUserRepository.getUser(userId);
    }

    @PostMapping("/user")
    public ResponseEntity<Void> postUser(@RequestBody User user) {
        sampleUserRepository.createUser(user);
        URI location = ServletUriComponentsBuilder.fromCurrentRequest()
         .path("/user/{userId}")
         .buildAndExpand(user.userId)
         .toUri();
        HttpHeaders httpHeaders = new HttpHeaders();
        httpHeaders.setLocation(location);

        return new ResponseEntity<>(httpHeaders, HttpStatus.CREATED);
    }

    @PutMapping("/user/{userId}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void putUser(@PathVariable Integer userId, @RequestBody User user) {
        sampleUserRepository.updateuserName(user.getUserName(), userId);
    }

    @DeleteMapping("/user/{userId}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void deleteUser(@PathVariable Integer userId) {
        sampleUserRepository.deleteUser(userId);
    }
}

導入の流れ

pom.xmlのdependenciesに「springfox-swagger2」と「springfox-swagger-ui」を追加

まずは、pom.xmlを修正します。dependenciesに、以下を追加してください。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.7.0</version>
</dependency>

Spring Boot 1.5.10とswagger-ui 2.8.0, swagger-ui 2.8.0を利用する場合、作成したWebドキュメントへのリクエストが404になってしまう場合があります。この問題は、/swagger-ui.html のlocationを自分でBeanを定義すると解決できるようなのですが、自分の環境ではうまく動作しなかったためswaggerのライブラリはバージョン2.7.0を利用しています。(参考

JavaConfigに@EnableSwagger2を付与

次に、導入するアプリケーションのJavaConfigに@EnableSwagger2を付与します。Swagger用のJavaConfigを用意している場合はそのJavaConfigに、用意していない場合はApplicationクラス(SpringApplication.run()があるクラス)につけるだけでOKです。

@SpringBootApplication
@EnableSwagger2
public class SampleWebApplication {
    public static void main(String[] args) {
        SpringApplication.run(SampleWebApplication.class, args);
    }
}

動作確認

アプリケーションを起動して、localhost:8080/swagger-ui.htmlにアクセスすると、Webドキュメントが生成されています。 f:id:dais39:20180325234243p:plain

おわりに

今回は、既存のRESTful APIサーバアプリケーションにSwaggerを導入して、Webドキュメントを自動生成しました。ドキュメントのレイアウトや細かい設定もJavaConfigで設定できるので、これをきっかけにSwaggerを導入してみるのも良いと思います。

参考

qiita.com