Swagger2 生成 Spring Boot API 文档

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。本文主要介绍了在 Spring Boot 添加 Swagger 支持， 生成可自动维护的 API 文档。

POM 文件

在pom.xml中加入Swagger2的依赖

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

代码支持

其次我们需要在代码中添加支持，于 Application 同级目录添加 Swagger 配置类，类名随意，但需要增加@EnableSwagger2和@Configuration注解，如下：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket config() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.pxx.xxx.controller"))
                .build();
    }
    //构建Api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Blog系统API文档")
                .contact(new Contact("作者", "访问地址", "联系方式"))
                .build();
    }
}

通过@Configuration注解，让Spring来加载该类配置，@EnableSwagger2注解来启用Swagger2。

再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore注解的API）

PS:这里需要注意的是.apis(RequestHandlerSelectors.basePackage("com.pxx.xxx.controller")) 指定了 Swagger 的扫描包名， 假如不指定此项， 在 Spring Boot 项目中， 会生成 base-err-controller 的 api 接口项。

访问地址

Ok. 接下来运行项目， 访问 http://项目启动地址/v2/api-docs , 就可以访问到生成的文档的json结构. (如下图 )

具体结构可参阅 Swagger官方示例

Swagger UI地址: 访问 http://项目启动地址//swagger-ui.html

注解

OK. 现在所有工作基本就绪，通过添加相应注解就可以快速生成相关接口文档, 这也是个人认为比较好的一点。

这里开始编写自己的RESTful Controller，跟正常开发没什么区别。主要是接口方法上面新增了几个注解：

• 通过@ApiOperation注解来给API增加说明
• 通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明
• 通过@ApiIgnore来忽略那些不想让生成RESTful API文档的接口

@Api(description = "文章操作相关接口")
@RestController
@RequestMapping("/article")
public class ArticleController {
    private final Logger logger = LoggerFactory.getLogger(ArticleController.class);

    @Autowired
    private BlogService blogService;

    @Autowired
    private JsonMapper jsonMapper;

    @Autowired
    private Environment env;

    @Autowired
    private PxxHttp pxxHttp;

    @ApiOperation(value="创建文章", notes="")
    @RequestMapping(value = {"/create"} , method = RequestMethod.POST)
    MessageModel create(@ApiParam @RequestParam("params") String params) throws IOException {

        return result;
    }

    @ApiOperation(value="更新文章", notes="")
    @RequestMapping(value = "/update", method = RequestMethod.POST)
    public @ResponseBody
    MessageModel update(@ApiParam @RequestParam("params") String params) throws Exception {

        return result;
    }

    @ApiOperation(value="mns更新文章", notes="")
    @RequestMapping(value = "/updatearticle", method = RequestMethod.POST)
    public @ResponseBody
    MessageModel updateArticle(@ApiParam @RequestParam("params") String params) throws Exception {

        return result;
    }

}

• @Api(description = "") : 对整个 Controller 的定义做一个解释
• @ApiOperation(value="", notes="") : 对 Controller 内 function 定义的内容作一解释
• @ApiParam : 添加到参数前， Swagger 会自动生成 API 文档中对参数的标示

 demo:

 　　Swagger2: 

package com.osp.ethscan.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 *
 * @author zhangmingcheng
 * @date 2018年9月25日
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
				.apis(RequestHandlerSelectors.basePackage("com.osp.ethscan.controller")).paths(PathSelectors.any())
				.build();
	}

	/**
	 * 构建Api文档的详细信息函数
	 *
	 * @return
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("osp-etherscan api文档")
				.description("简单优雅的restful风格，https://www.cnblogs.com/zhangmingcheng")
				.contact(new Contact("zmcheng", "", ""))
				.termsOfServiceUrl("https://www.cnblogs.com/zhangmingcheng").version("1.0").build();
	}
}

　　 Controller: 

package com.osp.ethscan.controller;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.osp.ethscan.entity.UserEntity;
import com.osp.ethscan.mapper.UserMapper;
import com.osp.ethscan.service.MailService;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import springfox.documentation.annotations.ApiIgnore;

@Api(description = "springboot学习测试相关接口")
@RestController
@RequestMapping(value = "/books")
public class UserController {

	@Autowired
	private UserMapper userMapper;

	@Autowired
	private MailService mailService;

	@ApiOperation(value = "获取用户列表", notes = "")
	@RequestMapping(value = "/getUsers", method = { RequestMethod.GET })
	public List<UserEntity> getUsers() {
		List<UserEntity> users = userMapper.getAll();
		mailService.sendSimpleMail("18753377530@163.com", "test simple mail", " hello this is simple mail");
		return users;
	}

	// 如果请求参数在url上,@ApiImplicitParam上加paramType = "path"
	@RequestMapping(value = "/{id}", method = { RequestMethod.GET })
	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
	@ApiOperation(value = "获取用户信息", notes = "根据url的id来获取用户信息")
	public UserEntity getUser(@PathVariable Long id) {
		UserEntity user = userMapper.getOne(id);
		return user;
	}

	@RequestMapping("/add")
	public void save(UserEntity user) {
		userMapper.insert(user);
	}

	@ApiIgnore // 使用该注解忽略这个API
	@RequestMapping(value = "update")
	public void update(UserEntity user) {
		userMapper.update(user);
	}

	@ApiIgnore // 使用该注解忽略这个API
	@RequestMapping(value = "/delete/{id}")
	public void delete(@PathVariable("id") Long id) {
		userMapper.delete(id);
	}

}