SpringBoot之Swagger2文档生成

1、Swagger2介绍

编写和维护接口文档是每个程序员的职责，前面我们已经写好的接口现在需要提供一份文档，这样才能方便调用者使用。考虑到编写接口文档是一个非常枯燥的工作，我们采用Swagger2这套自动化文档工具来生成文档，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。

2、SpringBoot开启Swagger2支持

第一步：在pom.xml中加入Swagger2的依赖

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

第二步：创建Swagger2配置类

package com.offcn.config;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration

@EnableSwagger2

public class SwaggerConfig {

public Docket createRestApi() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.select()

.apis(RequestHandlerSelectors.basePackage("com.offcn.controller"))

.paths(PathSelectors.any())

.build();

}

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("Spring Boot中使用Swagger2构建RESTful APIs")

.description("优就业")

.termsOfServiceUrl("http://www.ujiuye.com/")

.contact("Sunny")

.version("1.0")

.build();

}

3、修改Controller增加文档注释

通过@ApiOperation注解来给API增加说明通过@ApiImplicitParams@ApiImplicitParam注解来给参数增加说明

/**

* 更新指定id用户信息

* @param id

* @param user

* @return

@PutMapping("/{id}")

@ApiOperation(value="更新指定id用户信息", notes="根据id更新用户信息")

@ApiImplicitParams({

@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),

@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")

})

public String updateUser(@PathVariable("id") Long id,User user) {

user.setId(id);

userRepository.saveAndFlush(user);

return "success";

}

/***

* 删除指定id用户

* @param id

* @return

@DeleteMapping("/{id}")

@ApiOperation(value="删除指定id用户信息", notes="根据id删除用户信息")

@ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "Long")

public String deleteUser(@PathVariable("id") Long id) {

userRepository.deleteById(id);

return "success";

}

4、查看Swagger2文档

重启应用访问地址：http://localhost:8080/swagger-ui.html

点开每个接口，可以查看接口详情