Swagger最基础整理(附赠项目源码和视频)
一、Swagger简介
1、Swagger简介
Swagger是一套围绕Open API规范构建的开源工具,可以帮助设计,构建,记录和使用REST API。
Swagger工具包括的组件:
Swagger Editor :基于浏览器编辑器,可以在里面编写Open API规范。类似Markdown具有实时预览描述文件的功能。
Swagger UI:将Open API规范呈现为交互式API文档。用可视化UI展示描述文件。
Swagger Codegen:将OpenAPI规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成html格式和cwiki形式的接口文档,同时也可以生成多种言语的客户端和服务端代码。
Swagger Inspector:和Swagger UI有点类似,但是可以返回更多信息,也会保存请求的实际参数数据。
Swagger Hub:集成了上面所有项目的各个功能,你可以以项目和版本为单位,将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作,需要注册账号,分免费版和收费版。
使用Swagger,就是把相关的信息存储在它定义的描述文件里面(yml或json格式),再通过维护这个描述文件可以去更新接口文档,以及生成各端代码。
2、官网
https://swagger.io/
3、项目代码
https://download.csdn.net/download/weixin_44624117/85357475
4、参考视频
https://www.bilibili.com/video/BV1yi4y1F7KP
https://download.csdn.net/download/weixin_44624117/85374341
二、初始化Swagger项目
1、pom文件
SpringBoot集成Swagger => springfox,两个jar包
- Springfox-swagger2
- swagger-springmvc
<!--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>
2、Swagger配置类
package com.lydms.swaggerdemo.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
}
或者在启动类上加上@EnableSwagger2
(效果相同):
会扫表当前类所在包,以及子包中所有类型的注解。
package com.lydms.swaggerdemo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@EnableSwagger2
@SpringBootApplication
public class SwaggerDemoApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerDemoApplication.class, args);
}
}
3、Controller接口
package com.lydms.swaggerdemo.web;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/test")
public class UserController {
@RequestMapping("/user")
public String addUser() {
return "hello world";
}
}
4、页面展示
http://ip:port/swagger-ui.html
三、Swagger配置
1、枚举参数配置
1.1 RequestHandlerSelectors
.apis(RequestHandlerSelectors.basePackage("com.lydms.swaggerdemo"))
any()
// 扫描所有,项目中的所有接口都会被扫描到
RequestHandlerSelectors.any()
none()
// 不扫描接口(RequestHandlerSelectors配置如何扫描接口)
RequestHandlerSelectors.none()
basePackage()
// 根据包路径扫描接口
RequestHandlerSelectors.basePackage("com.lydms.swaggerdemo")
withMethodAnnotation()
// 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)
withClassAnnotation()
// 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
RequestHandlerSelectors.withClassAnnotation(RestController.class)
1.2 PathSelectors
any()
//
PathSelectors.any()
none()
//
PathSelectors.none()
ant()
// paths()。过滤什么路径
PathSelectors.ant("/test/**")
regex()
// 通过正则表达式路径url,进行文档生成
PathSelectors.regex("/test")
2、Swagger基本信息配置
-
Docket
:摘要对象,通过对象配置描述文件的信息。 -
apiInfo
:设置描述文件中info。参数类型ApiInfo
。 -
select()
:返回ApiSelectorBuilder
对象,通过对象调用build()可以创建Docket对象 -
ApiInfoBuilder
:ApiInfo构建器。
//Swagger信息配置
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(this.apiInfo());
}
//配置文档信息
private ApiInfo apiInfo() {
Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
return new ApiInfoBuilder()
.title("Swagger学习") // 标题
.description("学习演示如何配置Swagger") // 描述
.version("v1.0") // 版本
.termsOfServiceUrl("http://terms.service.url/组织链接") // 组织链接
.contact(contact) // 联系人信息
.license("Apach 2.0 许可") // 许可
.licenseUrl("许可链接") // 许可连接
.extensions(new ArrayList<>()) // 扩展
.build();
}
配配置后展示:
3、配置扫描包位置
配置扫描方式:
select()
:paths()
:过滤接口的路径apis()
方法设置哪个包中内容被扫描
//Swagger信息配置
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(this.apiInfo())
.select() // 通过.select()方法获取Docket中的选择器,去配置扫描接口。RequestHandlerSelectors配置如何扫描接口
.apis(RequestHandlerSelectors.basePackage("com.lydms.swaggerdemo")) // 根据包路径扫描接口
.apis(RequestHandlerSelectors.any()) // 扫描所有,项目中的所有接口都会被扫描到
.apis(RequestHandlerSelectors.none()) // 不扫描接口(RequestHandlerSelectors配置如何扫描接口)
// 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
// 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
.paths(PathSelectors.ant("/test/**")) //paths()。过滤什么路径
.paths(PathSelectors.regex("/test")) //通过正则表达式路径url,进行文档生成
.build();
}
paths中PathSelectors
参数:
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制
4、配置Swagger开关
关闭Swagger页面展示
return new Docket(DocumentationType.SWAGGER_2)
.enable(false); //配置是否启用Swagger,如果是false,在浏览器将无法访问
根据当前所处的环境,决定是否开启Swagger。
指定当前环境(dev环境)
spring.profiles.active=dev
配置代码:
//Swagger信息配置
public Docket docket(Environment environment) {
// 设置要显示swagger的环境
Profiles profiles = Profiles.of("dev", "int", "test");
// 判断当前是否处于该环境
// 通过 enable() 接收此参数判断是否要显示
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.enable(flag) //配置是否启用Swagger,如果是false,在浏览器将无法访问
.select()
.apis(RequestHandlerSelectors.basePackage("com.lydms.swaggerdemo")) // 根据包路径扫描接口
.build();
}
5、配置多个分组
//配置多个分组
@Bean
public Docket docket1() {
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2() {
return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3() {
return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}
6、自定义注解不扫描包
自定义注解
package com.lydms.swaggerdemo.anno;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface MySwagger {
}
Swagger配置
//5、自定义:使用注解,不生成文档
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(this.apiInfo())
.select()
// 注解加载指定方法上不展示(Predicates.not)取反
.apis(
Predicates.not( //取反
RequestHandlerSelectors.withMethodAnnotation(MySwagger.class) //根据注解配置
))
.build();
}
使用注解
/**
* @MySwagger注解:自定义忽略生成Swagger文档
*/
@MySwagger
@GetMapping("/testInterface")
public String notSwagger(int pageNo, int pageSize) {
return "pageNo=" + pageNo + "; pageNo=" + pageSize;
}
四、API中使用Swagger
1、Swagger注解
@Api
:用在请求的类上,表示对类的说明
@Api:用在请求的类上,表示对类的说明
tags="说明该类的作用,可以在UI界面上看到的注解"
value="该参数没什么意义,在UI界面上也看到,所以不需要配置"
@ApiOperation
:用在请求的方法上,说明方法的用途、作用
@ApiOperation:用在请求的方法上,说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiImplicitParams
:用在请求的方法上,表示一组参数说明
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· div(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
@ApiResponses
:用在请求的方法上,表示一组响应
@ApiResponses:用在请求的方法上,表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiIgnore
: 忽略文档或者忽略方法接口生成
@ApiIgnore: 忽略文档或者忽略方法接口生成
@ApiModel
:用于响应类上,表示一个返回响应数据的信息
@ApiModel:用于响应类上,表示一个返回响应数据的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty
:用在属性上,描述响应类的属性
@ApiModelProperty:用在属性上,描述响应类的属性
2、Controller中使用
2.1 @Api( )
@Api是类上注解。控制整个类生成接口信息的内容。
-
tags
:类的名称。可以有多个值,多个值表示多个副本。 -
description
:描述,已过时。
@Api(tags = "Swagger测试接口")
@RestController
@RequestMapping("/test")
public class UserController {
}
2.2 @ApiOperation()-类/方式
@ApiOperation写在方法上,对方法进行总体描述
-
value
:接口描述 -
notes
:提示信息
@ApiOperation( value = "新增用户")
@ApiResponses({@ApiResponse(code = 200, message = "OK", response = MyUser.class)
@PostMapping("/user")
public MyUser user() {
MyUser myUser = new MyUser();
myUser.setName("张三");
myUser.setAge(18);
myUser.setId("123123123");
System.out.println(myUser.toString());
return myUser;
}
2.3 @ApiParam()
@ApiParam写在方法参数前面。用于对参数进行描述或说明是否为必添项等说明。
-
name
:参数名称 -
value
:参数描述 -
required
:是否是必须
@GetMapping("/user01")
public MyUser myUser(@ApiParam(name="用户名",value = "新增用户时提供的用户名",required = true) String username,
@ApiParam(name = "密码",value = "新增用户时提供的密码",required = true)String password) {
MyUser myUser = new MyUser();
myUser.setName(username);
myUser.setPassword(password);
return myUser;
}
2.4 @ApiResponses()
- @ApiOperation(value = “新增用户”)
- @ApiResponses({@ApiResponse(code = 200, message = “OK”, response = MyUser.class)})
@ApiOperation( value = "新增用户")
@ApiResponses({@ApiResponse(code = 200, message = "OK", response = MyUser.class)
@PostMapping("/user")
public MyUser user() {
MyUser myUser = new MyUser();
myUser.setName("张三");
myUser.setAge(18);
myUser.setId("123123123");
System.out.println(myUser.toString());
return myUser;
}
2.5 @ApiImplicitParams()
@ApiImplicitParam
用在方法上,表示单独的请求参数,总体功能和@ApiParam类似。
-
name
:属性名 -
value
:描述 -
required
:是否是必须的 -
paramType
:属性类型 -
dataType
:数据类型
/**
* @ApiImplicitParams:对入参进行解析注解。等同于@ApiParam
*/
@GetMapping("/testPage")
@ApiImplicitParams({
@ApiImplicitParam(name = "pageNo", value = "第几页", required = true, paramType = "字符串", defaultValue = "1"),
@ApiImplicitParam(name = "pageSize", value = "每页显示多少条", required = true, paramType = "字符串", defaultValue = "10")
})
public String page(String pageNo, String pageSize) {
return "pageNo=" + pageNo + "; pageNo=" + pageSize;
}
2.6 @ApiIgnore()
@ApiIgnore用于方法或类或参数上,表示这个方法或类被忽略。
/**
* @ApiIgnore:忽略生成API帮助文档
*/
@ApiIgnore
@GetMapping("/testInterface")
public String ignore(int pageNo, int pageSize) {
return "pageNo=" + pageNo + "; pageNo=" + pageSize;
}
3、model中使用Swagger
3.1 @ApiModel()
@ApiModel是类上注解,主要应用Model,也就是说这个注解一般都是写在实体类上。
-
value
:名称 -
description
:描述
3.2 @ApiModelProperty()
@ApiModelProperty可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容。
-
value
:描述 -
name
:重写属性名 -
required
:是否是必须的 -
example
:示例内容 -
hidden
:是否隐藏。
package com.lydms.swaggerdemo.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel(value = "com.lydms.swaggerdemo.entity.MyUser", description = "新增用户参数")
public class MyUser {
@ApiModelProperty(value = "ID")
private String id;
@ApiModelProperty(value = "名称",name = "test",required = true,example = "张三",hidden = true)
private String name;
@ApiModelProperty(value = "年龄")
private int age;
@ApiModelProperty(value = "密码")
private String password;
}