QuickStart
官方网站：https://swagger.io/
项目中使用swagger需要springfox
- swagger2
- swagger-ui
一、集成
- 新建一个SpringBoot-web项目
- 导入swagger依赖
<!--Https://mvnrepository.com/artifact/io.springfox/springfox-swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--Https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
- 配置SwaggerConfig
@Configuration
@EnableSwagger2 // 开启swagger2
public class SwaggerConfig {
}
- 测试运行 访问地址：http://localhost:8080/swagger-ui.html
二、配置
(1) 基本信息
@Configuration
@EnableSwagger2 // 开启swagger2
public class SwaggerConfig {
// 配置swaggerDocket的bean实例
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
// 配置swagger信息
private ApiInfo apiInfo() {
// 作者信息
Contact contact = new Contact("AnKh", "https://www.jianshu.com/u/0aaeea7cbd2d", "a972080233@163.com");
return new ApiInfo(
"Swagger Test",
"Api Documentation",
"1.0",
"https://www.jianshu.com/u/0aaeea7cbd2d",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
}
}
(2) 配置扫描接口及开关
// 配置swaggerDocket的bean实例
@Bean
public Docket docket(Environment environment) {
// 设置显示的 Swagger环境
Profiles profiles = Profiles.of("dev", "test");
// 通过environment.acceptsProfiles判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)
.select()
// enable 是否启动swagger false: 不能启动
// RequestHandlerSelectors: 配置扫描接口的方式
// basePackage: 指定扫描的包
// any(): 扫描全部
// none(): 都不扫描
// withClassAnnotation: 扫描类上注解
// withMethodAnnotation: 扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("net.ankh.swagger_study.controller"))
// paths() 过滤指定路径 PathSelectors.
.build();
}
swagger在生产环境时使用,在正式环境中关闭
- 判断环境
- 注入enable中的值
(3) 配置API文档分组
1. 配置多个分组
在SwaggerConfig中配置多个Docket
@Bean
public Docket docketOne() {
return new Docket(DocumentationType.SWAGGER_2).groupName("One");
}
@Bean
public Docket docketTwo() {
return new Docket(DocumentationType.SWAGGER_2).groupName("Two");
}
@Bean
public Docket docketThree() {
return new Docket(DocumentationType.SWAGGER_2).groupName("Three");
}
(4) 常用注解
@Api()
用于类，表示标识这个类是swagger的资源
- tags–表示说明，当tags存在多个值时，会生成多个list
@Api(tags = {"One", "Two"})
@Api(tags = {"One", "Two"})
@ApiOperation()
用于方法，表示一个http请求的操作
- value–方法描述
- notes–提示内容
- tags–可以重新分组（视情况而用）
@ApiParam()
用于方法，参数，字段说明； 表示对参数的添加元数据（说明或是否必填等）
- name–参数名
- value–参数说明
- required–是否必填
@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {
@ApiOperation(value="获取用户信息",notes="注意问题点")
@GetMapping("/getUserInfo")
public User getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id, @ApiParam(name="username",value="用户名") String username) {
// userService可忽略，是业务逻辑
User user = new User();
return user;
}
}
swagger_@ApiParam
@ApiModel()
用于类，表示对类进行说明，用于参数用实体类接收
- value–表示对象名
- description–描述 都可省略
@ApiModelProperty()
用于方法，字段，表示对model属性的说明或者数据操作更改
- value–字段说明
- name–重写属性名字
- dataType–重写属性类型
- required–是否必填
- example–举例说明
- hidden–隐藏
@ApiModel(value = "用户实体类", description = "一些描述信息")
public class User {
@ApiModelProperty(value = "用户名称", required = true, example = "zhangsan", name = "user", dataType = "String")
private String username;
private String password;
}
swagger_Models
@ApiIgnore()
用于类，方法，方法参数，表示这个方法或者类被忽略
@ApiImplicitParam()
用于方法，表示单独的请求参数
@ApiImplicitParams()
用于方法，包含多个 @ApiImplicitParam
- name–参数ming
- value–参数说明
- dataType–数据类型
- paramType–参数类型
- example–举例说明
@ApiOperation("查询测试")
@GetMapping("select")
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="用户名称",dataType="string", paramType = "query", example="张三"),
@ApiImplicitParam(name="id",value="用户ID",dataType="long", paramType = "query")
})
public void select(){
}
swagger_@ApiImplicitParams
【注意】在正式环境中，关闭Swagger
参考资料
