当前位置：首页 > news >正文

一文教你使用Swagger---适合新手小白（结合实战）

news 2025/9/11 12:26:48

1.什么是Swagger

Swagger----在线自动生成接口文档，是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，可用于接口的文档在线自动生成以及功能测试。

2.Swagger与OpenAPI

OpenAPI规范OpenAPI Specification以前叫做Swagger规范，是REST API的API描述格式。Open API 文件允许描述整个API,包括：

每个访问地址的类型，POST或GET
每个操作的参数，包括输入输出参数
认证方法
连接信息、声明，使用团队和其他信息

OpenAPI规范可以使用YAML或jSON格式进行编写，这样更利于阅读。Swagger是一套围绕Open API规范构建的开源工具，可以帮助设计、构建，记录和使用REST API。

3.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格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

4.Springfox的使用

1.引入依赖

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency>
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>

2.启动类上加注解

3.启动后浏览器输入对应端口号+/swagger-ui.html.

我的是 http://localhost:8080/swagger-ui.html#

4.效果如下

5.SwaggerUI的使用和配置

访问swagger-ui.html可以在页面中看到所有需要生成接口文档的控制器名称。

每个控制包含该控制器下所有的方法及访问方式。如果使用的是@RequestMapping进行映射，将在显示所有的请求方式，如上图所示。假设使用@PostMapping，那么就只会显示Post的那个。

点击某个请求方法中的try it out

输入对应的参数，然后点击execute执行，将会出现Request URL以及相应结果。

5.Swagger配置类的实现

效果：

6.自定义注解排除扫描

1.创建NoIncludeSwagger接口

package cn.itcast;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 NoIncludeSwagger {
}

2.配置到Swagger配置类中

3.在需要排除了类上加上注解即可

效果如下：

7.设置范围

所谓设置范围实际就是可以设置满足什么样规则的url能被生成在接口文档中，可以使用正则表达式进行匹配。

下面例子中表示只有以/demo/开头的url才能被swagger生成接口文档。

如果希望所有接口都使用Swagger：

paths(PathSelectors.any())

8.常用注解

1. Api

注解名称	参数	含义
@Api		类上注解，控制整个类生成接口信息的内容
	tags	类的名称，可以有多个值，多个值表示多个副本
	description	概述

类上注解控制整个类生成接口信息的内容

package cn.itcast.controller;import cn.itcast.NoIncludeSwagger;
import cn.itcast.domain.People;
import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/people")
@Api(tags = {"myDemo"},description = "描述")
public class DemoController {
//    @NoIncludeSwagger@PostMapping("/getPeople")public People getPeople(Long id, String name){People peo = new People();peo.setId(id);peo.setName(name);peo.setAddress("北京");return peo;}
}

2. ApiOperation

注解名称	参数	含义
@ApiOperation		写在方法上，对方法进行总体描述
	value	接口描述
	notes	提示信息

@RestController
@RequestMapping("/people")
@Api(tags = {"myDemo"},description = "描述")
public class DemoController {
//    @NoIncludeSwagger@ApiOperation(value = "获取人员信息",notes = "通过人员编号和名称获取人员信息")@PostMapping("/getPeople")public People getPeople(Long id, String name){People peo = new People();peo.setId(id);peo.setName(name);peo.setAddress("北京");return peo;}
}

3. ApiParam

注解名称	参数	含义
@ApiParam		写在方法参数前面。用于对参数进行描述或说明是否为必填项等
	name	参数名称
	value	参数描述
	required	是否是必须

4. ApiModel

注解名称	参数	含义
@ApiParam		是类上注解，主要应用Model，也就是说这个注解一般都是写在实体类上
	value	名称
	description	描述

5. ApiModelProperty

注解名称	参数	含义
@ApiModelProperty		一般用于方法，属性的说明
	value	字段说明
	name	重写属性名
	required	是否必须
	example	示例内容
	hiden	是否隐藏

6. ApiIgnore

注解名称	含义
@ApiIgnore	用于方法或类或参数上，表示这个方法或类被忽略，和之前讲解的自定义注解@NotIncludeSwagger效果类似。只是这个注解是Swagger内置的注解，而@NotIncludeSwagger是我们自定义的注解

7. ApiImplicitParam

注解名称	参数	含义
@ApiImpliciParam		用在方法上，表示单独的请求参数，总体功能和@ApiParam类似。
	value	对接口中的参数进行简单必要的描述
	name	描述接口中参数的名称
	required	是否必须
	paramType	接口中的参数应该用在那个地方，常用的位置有：header,query,path
	dataType	接口中参数的类型