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

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

整体结构

imagepng

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里面属性的注解,定义一个属性的描述。

效果展示

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

更换风格

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

源码地址

本文为博主原创文章,未经博主允许不得转载。
更多内容请访问:IT源点

注意:本文归作者所有,未经作者允许,不得转载