【SpringBoot 实战】整合 swagger2

写完接口，你需要写接口文档，一般都是接口文档都是独立的，你需要花个几十分钟写个文档。

使用了 swagger 之后，你只需要加几个配置，然后重启下项目，你的接口文档就形成了。

整体结构

pom 配置

需要引入以下 jar 包

<parent>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-parent</artifactId>
	<version>2.1.1.RELEASE</version>
	<relativePath/> <!-- lookup parent from repository -->
</parent>
	
<dependencies>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-web</artifactId>
	</dependency>
	<dependency>
		<groupId>org.projectlombok</groupId>
		<artifactId>lombok</artifactId>
		<optional>true</optional>
	</dependency>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-test</artifactId>
		<scope>test</scope>
	</dependency>
	<!--添加swagger2核心jar -->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.6.1</version>
	</dependency>
	<!--添加Swagger-UI依赖 -->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
		<version>2.7.0</version>
	</dependency>
</dependencies>

​

核心代码

在 ChapterSwagger2Application 类中加入注解：

@EnableSwagger2
​

新增 Swagger2 配置类，主要实现了 swagger 的一些配置；

@Bean
public Docket createRestApi() {
	ParameterBuilder tokenPar = new ParameterBuilder();

	List<Parameter> pars = new ArrayList<Parameter>();
	tokenPar.name("token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
	pars.add(tokenPar.build());

	return new Docket(DocumentationType.SWAGGER_2)
			.apiInfo(apiInfo()).enable(enableSwagger)
			.select()
			.apis(RequestHandlerSelectors.basePackage("com.cimu.swagger.controller"))
			.paths(PathSelectors.any())
			.build()
			.globalOperationParameters(pars);
}
​

DemoController 类：里面实现了一些实例；

注解说明

@Api：对 controller 类进行描述。比如：名称，描述，标签，权限，是否显示等。
@ApiOperation：对某个方法进行描述。
@ApiImplicitParam：对单个参数进行描述。可以定义参数名称，名称描述，是否必填，参数类型（path、query、body、header、form）等。
@ApiImplicitParams：定义多个 @ApiImplicitParam，如：

@ApiImplicitParams({
  @ApiImplicitParam(name = "mobile", value = "手机号", required = true, paramType = "query"),
  @ApiImplicitParam(name = "name", value = "名称", required = true, paramType = "query")
})
​

@ApiResponse：对返回值进行设置。
@ApiResponses：对多个返回值进行设置，如：

@ApiResponses({
  @ApiResponse(code = 200, message = "返回数据", response = DemoDto.class)
})
​

@ApiIgnore：可以忽略方法里面的参数，忽略某个方法，可以忽略某个 controller。
@ApiModel：在 model 对象上注解。
@ApiModelProperty：model 里面属性的注解，定义一个属性的描述。

效果展示

可以直接在接口文档里面测试接口，

更换风格

如果你觉得系统提供的文档不喜欢，或者看起来不方便，那么可以使用开源的一些皮肤。
可以查看 https://www.cnblogs.com/myhappylife/p/9403563.html。
具体的使用方法也有。

源码地址