Spring Cloud微服务项目搭建系列文章(七)：API处理之Swagger集成

上一篇异常处理我们讲解了关于异常的处理，本文主要介绍对于API的处理。

本文项目地址：

源码地址

现在Spring对于web的处理分成2中方式：

一种是传统的webmvc的方式，基于http的

一种是基于reactor和netty实现的，webflux的方式。

因此Swagger也提供了2种集成方式，

webflux的实现

Swagger2集成Spring boot 2.1.12 基于WebFlux

可以看这篇文章，里面有详细的说明

Web的实现

POM的引入

  <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-bean-validators</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

配置实现

/**
 * API文档配置
 * 
 * @author 大仙
 *
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
	@Bean
	public Docket createRestApi(){
		ParameterBuilder builder = new ParameterBuilder();
		builder.parameterType("header").name(Constant.AUTHORIZATION)
		.description("header参数")
		.required(false)
		.modelRef(new ModelRef("string")); // 在swagger里显示header
		return new Docket(DocumentationType.SWAGGER_2).groupName("-接口文档")
				.apiInfo(new ApiInfoBuilder().title("接口文档")
						.contact(new Contact("朱维", "", "XXX")).version("1.0").build())
				.globalOperationParameters(Lists.newArrayList(builder.build()))
				.select()
				.apis(RequestHandlerSelectors.basePackage("com"))
				.paths(PathSelectors.any()).build();
	}
}

这样配置完成就OK了

Swagger使用

@Api：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

    l   code：数字，例如400

    l   message：信息，例如"请求参数没填好"

    l   response：抛出异常的类   

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

    l   @ApiModelProperty：描述一个model的属性

 

注意：@ApiImplicitParam的参数说明：

paramType：指定参数放在哪个地方	header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）-->请求参数的获取：@PathVariable body：（不常用） form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传	true | false
value：说明参数的意思
defaultValue：参数的默认值

访问 

启动相应的服务之后访问：http://localhost:端口/swagger-ui.html