前后端分离的时代,一个优秀的在线接口文档查看是比不可少的,这边介绍一款优秀的插件bootstrap-ui,目前我这边使用的版本是1.9.6,搭配SpringBoot,外加代码生成器,写代码简直是起飞,废话不多说,直接进入只用正题。
一、在pom引入maven的jar包
<!-- swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.22</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
这个是swagger2必要引入的pom包,在此基础上再引入以下jar包
<!-- swagger2 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
二、框架配置
完成了pom引入,就需要在框架内配置了,首先是启动类,需要在启动类加上@EnableSwagger2
@EnableSwaggerBootstrapUI
如下:
package com.swsk.web;
import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2
@EnableSwaggerBootstrapUI
@ComponentScan(basePackages = "com.swsk")
public class WebApplication {
public static void main(String[] args) {
SpringApplication.run(WebApplication.class, args);
}
}
其次就要在项目中加上java代码去配置swagger的分组、基本参数以及swagger改扫描你代码中那一个文件夹下的接口了,可以对其分组,在接口多的时候方便查找和管理,完整代码如下:
package com.swsk.web.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;
/**
* swagger配置文件
* @author cy
* @date 2020/10/23 10:25
* @desc
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 默认分组
* @return
*/
@Bean(value = "defaultApi")
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("全部接口")
.select()
// 当前包路径
.apis(RequestHandlerSelectors.basePackage("com.swsk.web.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 可配置分组接口,apis内配置对应接口路径即可
* @return
*/
@Bean(value = "groupRestApi")
public Docket groupRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("基础信息模块")
.select()
.apis(RequestHandlerSelectors.basePackage("com.swsk.web.controller.user"))
.paths(PathSelectors.any())
.build();
}
/**
* 构建api文档的详细信息函数
* @return
*/
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
//页面标题
.title("接口文档 API")
//创建人
.contact(new Contact("chengyi","http://www.baidu.com",""))
//版本号
.version("1.0")
//描述
.description("API 描述")
.build();
}
}
配置完就可以启动项目访问:http://localhost:8080/doc.html
三、代码规范
完成前面的配置,基本都能使用了,但是需要有良好的体验,代码规范是必不可少的,下面简单描述一下代码需要注意哪些细节。
@Api(value = "用户管理", tags = {"用户管理"}) //修饰整个类,描述Controller的作用
@ApiOperation( "添加用户") //用于方法;表示一个http请求的操作
@ApiImplicitParams({ //表示接口对应参数,example表示默认值
@ApiImplicitParam(name="startTime",value="开始时间 yyyy-MM-dd",dataType="string",example="2019-01-10"),
@ApiImplicitParam(name="endTime",value="结束时间 yyyy-MM-dd",dataType="string",example="2021-12-18"),
@ApiImplicitParam(name="deptName",value="部门名称",dataType="string"),
@ApiImplicitParam(name="keyword",value="关键字",dataType="string")})
@Api:修饰整个类,描述Controller的作用