文章目录
官网
官网： http://petstore.swagger.io/
swagger-bootstrap-ui 指南 ：
https://www.bookstack.cn/read/swagger-bootstrap-ui/3.md
导入依赖
swagger2依赖 + springfox-swagger-ui依赖 或者 swagger-bootstrap-ui依赖 或者2个都加
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
springfox-swagger-ui依赖
<!-- swagger2的依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
swagger-bootstrap-ui依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.3</version>
</dependency>
配置
swagger基础配置
swagger的简单配置，戳进Docket、ApiInfo、CONTACT看看源码
@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {
//创建一个Swagger配置的实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
//new ApiInfo的信息传给上面的Docket
public ApiInfo apiInfo() {
//CONTACT指的是作者的信息,name，url,qq邮箱
Contact contact = new Contact("swagger","http://petstore.swagger.io/","[email protected]");
return new ApiInfo(
"swagger文档",
"前后端交互的api",
"1.0",
"https://editor.csdn.net",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
swagger默认扫描包配置
//创建一个Swagger配置的实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// .enable(false) //是否启用swagger
.select()
//any() 都扫描、 none() 都不扫描、...
.apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller")) //扫描自定义的包
// .paths(PathSelectors.ant("com.example.swagger.xxx")) //过滤路径
.build();
}
在不同环境时更换swagger的开启
SwaggerConfig配置
//创建一个Swagger配置的实例
@Bean
public Docket docket(Environment environment) {
//设置要显示swagger的环境
Profiles profiles = Profiles.of("test","dev");
//判断不同环境中profiles的布尔值,并将enable传到enable(enable)方法中
Boolean enable = environment.acceptsProfiles(profiles);
System.out.println(enable);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(enable) //是否启用swagger
.select()
//any() 都扫描、 none() 都不扫描、...
.apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller")) //扫描自定义的包
// .paths(PathSelectors.ant("com.example.swagger.xxx")) //过滤路径
.build();
}
application.yml配置，(也可以写成多文件形式，里面配个端口号就行了，更换active的值)
#公共配置
spring:
profiles:
active: dev #使用名为pro的配置，这里可以切换成dev
---
#开发环境配置
spring:
profiles: dev #profiles属性代表配置的名称
server:
port: 8080
---
#生产环境配置
spring:
profiles: pro
server:
port: 8001
---
##测试环境配置
spring:
profiles: test
server:
port: 8002
swagger分组
//分组,可以创建多个Swagger配置的实例
@Bean
public Docket docket2() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("swagger2");
}
//创建一个Swagger配置的实例
@Bean
public Docket docket(Environment environment) {
//设置要显示swagger的环境
Profiles profiles = Profiles.of("test","dev");
//判断不同环境中profiles的布尔值,并将enable传到enable(enable)方法中
Boolean enable = environment.acceptsProfiles(profiles);
System.out.println(enable);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("swagger1") //组名
.enable(enable) //是否启用swagger
.select()
//any() 都扫描、 none() 都不扫描、...
.apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller")) //扫描自定义的包
// .paths(PathSelectors.ant("com.example.swagger.xxx")) //过滤路径
.build();
}
swagger的api注解
- User代码
package com.example.swagger.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "User", description = "user实体类")
public class User {
// @ApiModelProperty(name = "username",value = "用户名")
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty(name = "password",value = "密码")
private String password;
}
- UserController代码
package com.example.swagger.controller;
import com.example.swagger.pojo.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
@RestController
@ApiSort(value = 5)
@Api(value="用户controller",tags={"用户操作接口"})
public class UserController {
@PostMapping("/login")
@ApiOperationSort(value = 2)
@ApiOperation(value="登陆操作",notes="用户名:admin 密码:123456")
public String login(@RequestBody @ApiParam(name="User",value="用户对象",required=true) User user) {
System.out.println(user.getUsername() + " " + user.getPassword());
if(user.getUsername().equals("admin") && user.getPassword().equals("123456")) {
return "登陆成功!";
}else {
return "登陆失败!";
}
}
// @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
// name–参数名
// value–参数说明
// dataType–数据类型 lang String
// paramType- 参数的输入格式 : path, query, body, header, form 提交参数的方式，例如query是拼接在地址后为get请求，body是post请求...
@GetMapping("/login2")
@ApiOperationSort(value = 1)
@ApiOperation(value = "登陆操作2", notes = "用户名:admin 密码:123456")
@ApiResponses({@ApiResponse(code = 404, message = "路径不对"), @ApiResponse(code = 405, message = "服务器错误")} )
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "String", paramType = "query"),
@ApiImplicitParam(name = "password", value = "密码", required = true, dataType = "String", paramType = "query")
})
public String login2(String username, String password){
if(username.equals("admin") && password.equals("123456")) {
return "登陆成功!";
}else {
return "登陆失败!";
}
}
}
swagger-bootstrap-ui排序功能
这个排序功能是用在 swagger-bootstrap-ui，使用springfox-swagger-ui没有显示出效果(可能有什么地方要设置...)
- 接口排序@ApiOperationSort()
- 接口中的方法排序@ApiSort()
@Api(position = 5) 和 @ApiOperation(position = 1) postion的排序已经过时
使用 @ApiSort(value = 5) 和 @ApiOperationSort(value = 1) 代替
1 的优先级最大，依此递减
需要加上@EnableSwaggerBootstrapUI
@Configuration
@EnableSwagger2 //开启swagger2
@EnableSwaggerBootstrapUI //开启增强功能
public class SwaggerConfig { ... }
访问地址
- springfox-swagger-ui
http://localhost:8080/swagger-ui.html
- swagger-bootstrap-ui
http://localhost:8080/doc.html
效果
springfox-swagger-ui截图演示
swagger-bootstrap-ui截图演示
例子
链接：https://pan.baidu.com/s/1eqJDTx4VVYouxEzYxsRCIA
提取码：hv95
