swagger使用教程

大家好，欢迎来到IT知识分享网。

1 Swagger 简介

翻译：大摇大摆;神气十足

读音： [ˈswæɡər] 人称：（丝袜哥）

版本：swagger3比swagger2相比,配置更少，使用更加方便

官网：https://swagger.io/ （API Development for Eveyone）

在线编辑器：http://editor.swagger.io/

作用：简单但功能强大的API表达工具

配置或修改源码，达到对应功能：

• Swagger Codegen
• Swagger UI
• Swagger Editor
• Swagger Inspector
• Swagger Hub

2 使用

2.1 新建一个SpringBoot项目

目前 版本使用 2.5.5

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.5.5</version> </parent> 

2.2 引入依赖

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> 

整体个pom.xml如下

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>org.example</groupId> <artifactId>swagger</artifactId> <version>1.0-SNAPSHOT</version> <properties> <maven.compiler.source>1.8</maven.compiler.source> <maven.compiler.target>1.8</maven.compiler.target> </properties> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.5.5</version> </parent> <dependencies> <!--swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> <!--web--> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!--test--> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <version>2.5.5</version> <configuration> <!-- 如果没有该配置，热部署的devtools不生效 --> <fork>true</fork> </configuration> </plugin> </plugins> </build> </project> 

2.3 开启Swagger

在SpringBoot的启动类 添加@EnableOpenApi注解，开启Swagger支持

@EnableOpenApi @SpringBootApplication public class Starter extends SpringBootServletInitializer { 
    public static void main(String[] args) { 
    SpringApplication.run(Starter.class); } } 

2.4 新建 Controller.java控制器类

@RestController public class HelloWorldController { @RequestMapping("/helloWorld") public String helloWorld(){ return "helloWorld"; } } 

@RestController注解相当于@ResponseBody ＋ @Controller合在一起的作用

2.5 启动测试

1 hello返回结果

2 访问swagger-ui,查看接口文档

http://localhost:8080/swagger-ui/

注意，这个网址一定路径要写齐全 http://localhost:8080/swagger-ui/

结构如下

• 分组定义信息 区块
• API文档上信息区块
• 接口定义信息区块

2.6 Swagger注解描述接口

@Api(tags="hello类测试") @RestController public class HelloController { 
    @ApiOperation("测试方法") @RequestMapping("hello") public String hello(){ 
    return "helloWorld"; } } 

3 常用配置注解

3.1 @Api

用于请求的类上，表示对类的说明

• tags=“说明该类的作用，可以在ui界面上看到的注解”
• value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”

3.2 @ApiOperation

用在请求的方法上，说明方法的用途、作用

• value=“说明方法的用途、作用”
• notes=“方法的备注说明”

3.3 @ApiImplicitParams

用在请求的方法上，表示一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

​ name：参数名

​ value：参数的汉字说明、解释

​ required：参数是否必须传

​ paramType：参数放在哪个地方

​ header –> 请求参数的获取：@RequestHeader

​ query –> 请求参数的获取：@RequestParam

​ path（用于restful接口）–> 请求参数的获取：@PathVariable

​ div（不常用）

​ form（不常用）

​ dataType：参数类型，默认String，其它值dataType=“Integer”

​ defaultValue：参数的默认值

3.4 @ApiResponses：

用在请求的方法上，表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

• code：数字，例如400
• message：信息，例如”请求参数没填好”
• response：抛出异常的类

3.5 @ApiModel

用于响应类上，表示一个返回响应数据的信息

（这种一般用在post创建的时候，使用@RequestBody这样的场景，

请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiModelProperty：用在属性上，描述响应类的属性

3.6 实例一 参数注释说明

• @ApiImplicitParams
• @ApiImplicitParam

@GetMapping("query") @ApiImplicitParams({ 
    @ApiImplicitParam(name = "name",value = "姓名",required = true,paramType = "query"), @ApiImplicitParam(name = "age",value = "年龄",required = true,paramType = "query",dataType = "Integer") }) @ApiOperation("测试查询") public String search(String name,Integer age){ 
    return name+":"+age; } 

效果

实例二 实体注释说明

• @ApiModel
• @ApiModelProperty

新建 User类

@ApiModel("用户信息实体") public class User { 
    @ApiModelProperty("编码") private Integer id; @ApiModelProperty("姓名") private String name; @ApiModelProperty("年龄") private Integer age; /*get和set省略*/ public User() { 
    } public User(Integer id,String name, Integer age) { 
    this.id=id; this.name = name; this.age = age; } @Override public String toString() { 
    return "User{" + "id=" + id + ", name='" + name + '\'' + ", age=" + age + '}'; } } 

controller类

@PostMapping("add") @ApiOperation("测试添加") public String add(User user){ 
    return user.getName()+":"+user.getAge(); } 

效果

实例三 响应码

• @ApiResponses
• @ApiResponse

@GetMapping("/user/{id}") @ApiOperation("根据ID获取用户信息") @ApiImplicitParams({ 
   @ApiImplicitParam(name="id",value = "用户编号",required = true,paramType ="path")}) @ApiResponses({ 
    @ApiResponse(code=408,message = "错误1" ), @ApiResponse(code=400,message = "错误2" ), @ApiResponse(code=404,message = "错误3" ) }) public User load(@PathVariable("id") Integer id){ 
    return new User(id,"jack",32); } 

接口测试

Swagger-ui图形客户端提供了接口测试功能；

• 点击-Try it out
• 点击-Execute

API信息配置

源码

static { DEFAULT = new ApiInfo( "Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); } 

@Configuration public class Swagger3Config { 
    @Bean public Docket createRestApi() { 
    return new Docket(DocumentationType.OAS_30) // 指定swagger3.0版本 .groupName("开发组001") .select() .apis(RequestHandlerSelectors.basePackage("org.example.controller")) // 指定扫描的包 常用方式 .build() .apiInfo(createApiInfo()); } @Bean public ApiInfo createApiInfo(){ 
    return new ApiInfo( "Api Documentation", //标题 "XX项目Api文档",//描述 "3.0", //版本 "https://www.kszs.xyz",//团队链接 new Contact("小明", "https://www.kszs.xyz", "@.com"), "Apache 2.0", "https://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); } 

这些API信息主要作用是让前端开发人员看的，谁开发的接口，或者那个小组负责，有问题方便联系沟通。

Docket开关|过滤|分组 配置详解

开关设置 enable

开发环境才会用到swagger；正式环境需要关闭swagger;

原因：一个是安全问题，另外一个它会影响系统运行速度

enable

@Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) // 指定swagger3.0版本 /*其它省略*/ .enable(false) //关闭 .apiInfo(createApiInfo()); } 

设置过滤

apis (必选有调用select) 参数：

• any 所有都有效
• none都无效
• withClassAnnotation 根据类注解
• withMethodAnnotation 根据方法注解
• basePackage根据包路径（主要）

@Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) // 指定swagger3.0版本 /*其它省略先*/ .select() .apis(RequestHandlerSelectors.basePackage("org.example.controller")) .apiInfo(createApiInfo()); } 

最后都要加build方法

还有一个 paths方法 参数有

• any 匹配任意路径
• none都不匹配
• regex正则匹配

.apis(RequestHandlerSelectors.basePackage("/org/example/")) 

设置分组

groupName

.groupName("开发组001") 

结合过滤，通过apis的basePackage方法，弄2个组，分别扫描不同包路径，模拟分组开发

@GetMapping是一个组合注解，是@RequestMapping(method = RequestMethod.GET)的缩写

@PostMapping是一个组合注解，是@RequestMapping(method = RequestMethod.POST)的缩写

源码下载：https://download.csdn.net/download/Linlietao0587/

1 在pom.xml 添加

 <!--15、jwt 用到--> <!--15、jwt 用到--> <dependency> <groupId>com.auth0</groupId> <artifactId>java-jwt</artifactId> <version>3.10.3</version> </dependency> <!--16、swagger3 用到--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> 

2 starter.java 添加

@EnableOpenApi 

import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.*; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spi.service.contexts.SecurityContext; import springfox.documentation.spring.web.plugins.Docket; import java.util.ArrayList; import java.util.List; / * Swagger3 配置设置 */ @Configuration public class Swagger3Config { 
    @Bean public Docket createRestApi() { 
    return new Docket(DocumentationType.OAS_30) // 指定swagger3.0版本 .groupName("开发组001") .select() .apis(RequestHandlerSelectors.basePackage("xyz.kszs.controller")) // 指定扫描的包 常用方式 .build() .enable(false) //开关 .securitySchemes(securitySchemes()) .securityContexts(securityContexts()) .apiInfo(createApiInfo()); } @Bean public ApiInfo createApiInfo(){ 
    return new ApiInfo( "Api Documentation", //标题 "kszs项目Api文档", //描述 "3.0", //版本 "https://www.baidu.com", //团队链接 new Contact("林烈涛", "https://www.baidu.com", "@.com"), "Apache 2.0", "https://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); } / * 认证的安全上下文 Authorization */ private List<SecurityScheme> securitySchemes() { 
    List<SecurityScheme> securitySchemes = new ArrayList<>(); securitySchemes.add(new ApiKey("token", "token", "header")); return securitySchemes; } / * 授权信息全局应用 */ private List<SecurityContext> securityContexts() { 
    List<SecurityContext> securityContexts = new ArrayList<>(); securityContexts.add(SecurityContext.builder() .securityReferences(defaultAuth()) .forPaths(PathSelectors.any()).build()); return securityContexts; } / * 可添加token */ private List<SecurityReference> defaultAuth() { 
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything"); AuthorizationScope[] authorizationScopes = new AuthorizationScope[1]; authorizationScopes[0] = authorizationScope; List<SecurityReference> securityReferences = new ArrayList<>(); securityReferences.add(new SecurityReference("token", authorizationScopes)); return securityReferences; } }