一、这里使用的是bootstrap版的API文档
二、如何在项目中配置,步骤如下
1、在pom文件中添加jar依赖
-
<!-- Swagger -->
-
<dependency>
-
<groupId>io.springfox</groupId>
-
<artifactId>springfox-swagger2</artifactId>
-
<version>2.9.2</version>
-
</dependency>
-
<!-- 根据自己需求选择不同版本的UI -->
-
<!-- Swagger 官方UI jar包 -->
-
<!--<dependency>-->
-
<!--<groupId>io.springfox</groupId>-->
-
<!--<artifactId>springfox-swagger-ui</artifactId>-->
-
<!--<version>2.9.2</version>-->
-
<!--</dependency>-->
-
<!-- 萧明同学提供的 jar 包 -->
-
<dependency>
-
<groupId>com.github.xiaoymin</groupId>
-
<artifactId>swagger-bootstrap-ui</artifactId>
-
<version>1.9.3</version>
-
</dependency>
2、在application.yml文件中添加以下权限访问口令
-
spring:
-
profiles:
-
active: test
-
# Swagger Tag 排序
-
swagger:
-
ui-config:
-
# method<按方法定义顺序排序>
-
operations-sorter: method
-
basic:
-
enable: true
-
## Basic认证用户名
-
username: 自定义
-
## Basic认证密码
-
password: 自定义
3、在项目中创建swagger配置类
-
import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
-
import org.springframework.context.annotation.Bean;
-
import org.springframework.context.annotation.Configuration;
-
import springfox.documentation.builders.ApiInfoBuilder;
-
import springfox.documentation.builders.ParameterBuilder;
-
import springfox.documentation.builders.PathSelectors;
-
import springfox.documentation.builders.RequestHandlerSelectors;
-
import springfox.documentation.schema.ModelRef;
-
import springfox.documentation.service.ApiInfo;
-
import springfox.documentation.service.Parameter;
-
import springfox.documentation.spi.DocumentationType;
-
import springfox.documentation.spring.web.plugins.Docket;
-
import springfox.documentation.swagger2.annotations.EnableSwagger2;
-
import java.util.ArrayList;
-
import java.util.List;
-
/**
-
* @ClassName Swagger2Config
-
* @Description: TODO
-
* @Author wzwsq
-
* @Date 2020/6/29
-
* @Version V1.0
-
**/
-
@Configuration
-
@EnableSwagger2
-
@EnableSwaggerBootstrapUI
-
public class Swagger2Config {
-
/**
-
* 全局参数
-
*
-
* @return List<Parameter>
-
*/
-
private List<Parameter> parameter() {
-
List<Parameter> params = new ArrayList<>();
-
params.add(new ParameterBuilder().name("token")
-
.description("认证令牌")
-
.modelRef(new ModelRef("string"))
-
.parameterType("header")
-
.required(false).build());
-
return params;
-
}
-
//swagger2的配置文件,这里可以配置swagger2的一些基本的内容,比如扫描的包等等
-
@Bean
-
public Docket createRestApi() {
-
return new Docket(DocumentationType.SWAGGER_2)
-
.apiInfo(apiInfo())
-
.select()
-
//为当前包路径
-
.apis(RequestHandlerSelectors.basePackage("xxx.controller"))
-
.paths(PathSelectors.any())
-
.build().globalOperationParameters(parameter());
-
}
-
//构建 api文档的详细信息函数,注意这里的注解引用的是哪个
-
private ApiInfo apiInfo() {
-
return new ApiInfoBuilder()
-
//页面标题
-
.title("MY API")
-
//创建人
-
//版本号
-
.version("1.0")
-
//描述
-
.description("API 描述")
-
.build();
-
}
-
}
4、对于Controller类的API描述
-
@Api(tags = { "UsersController" }, description = "用户操作常用接口")
-
@RestController
-
@RequestMapping("/users/")
-
public class UsersController {
-
private static Logger logger = LoggerFactory.getLogger(UsersController.class);
-
@Autowired
-
private UsersService usersService;
-
@ApiOperation("根据用户id,查询用户信息")
-
@RequestMapping(value = "toDetail", method = RequestMethod.GET)
-
public JSONObject editUsers(@RequestParam("id")String id){
-
logger.info("------------toDetail ---------------");
-
JSONObject jsonObject = new JSONObject();
-
//根据用户id,获取用户信息
-
UsersModel usersModel=usersService.getUserById(id);
-
jsonObject.put("users",usersModel);
-
return jsonObject;
-
}
-
}
6、对于model类的API描述
-
@ApiModel(description = "用户请求模型")
-
public class UserRequest {
-
/**
-
* 用户名
-
*/
-
@ApiModelProperty("用户名")
-
private Integer userName;
-
/**
-
* 用户密码
-
*/
-
@ApiModelProperty("用户密码")
-
private Integer userPass;
-
}
5、启动springboot
无项目名访问地址如下
http://localhost:8080/doc.html
有项目名访问地址如下