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

Swagger生成接口在线文档

news 2025/7/18 5:22:24

OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上。

（https://github.com/OAI/OpenAPI-Specification）

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，Swagger是一个在线接口文档的生成工具，前后端开发人员依据接口文档进行开发。 (https://swagger.io/)

Spring Boot 可以集成Swagger，Swaager根据Controller类中的注解生成接口文档，只要添加Swagger的依赖和配置信息即可使用它。

1、依赖

Java在工程添加swagger-spring-boot-starter依赖
<!-- Spring Boot 集成 swagger -->
<dependency><groupId>com.spring4all</groupId><artifactId>swagger-spring-boot-starter</artifactId>
</dependency>

2、bootstrap.yml

Java在bootstrap.yml中配置swagger的扫描包路径及其它信息，base-package为扫描的包路径，扫描Controller类。
swagger:title: "系统在线测试"description: "内容系统管理系统对课程相关信息进行管理"base-package: com.jinshan.contentenabled: trueversion: 1.0.0

3.@EnableSwagger2Doc注解

在启动类中添加@EnableSwagger2Doc注解

4.类和方法上的注解

Bash@Api(value = "课程信息编辑接口",tags = "课程信息编辑接口")@RestController
public class CourseBaseInfoController {@ApiOperation("课程查询接口")@PostMapping("/course/list")public PageResult<CourseBase> list(PageParams pageParams, @RequestBody(required=false) QueryCourseParamsDto queryCourseParams){//....}}

5.模型类注解

Javapublic class PageParams {...@ApiModelProperty("当前页码")
private Long pageNo = 1L;@ApiModelProperty("每页记录数默认值")
private Long pageSize = 30L;
...
public class QueryCourseParamsDto {//审核状态
@ApiModelProperty("审核状态")private String auditStatus;//课程名称@ApiModelProperty("课程名称")private String courseName;}

6.Swaager的常用注解

Java
@Api：修饰整个类，描述Controller的作用@ApiOperation：描述一个类的一个方法，或者说一个接口@ApiParam：单个参数描述@ApiModel：用对象来接收参数@ApiModelProperty：用对象接收参数时，描述对象的一个字段@ApiResponse：HTTP响应其中1个描述@ApiResponses：HTTP响应整体描述@ApiIgnore：使用该注解忽略这个API@ApiError ：发生错误返回的信息@ApiImplicitParam：一个请求参数@ApiImplicitParams：多个请求参数

7.@ApiImplicitParam属性

使用Swagger可以进行接口的测试。

修改接口内容，添加一些测试代码

Java
@ApiOperation("课程查询接口")
@PostMapping("/course/list")
public PageResult<CourseBase> list(PageParams pageParams, @RequestBody(required=false) QueryCourseParamsDto queryCourseParams){CourseBase courseBase = new CourseBase();courseBase.setName("测试名称");courseBase.setCreateDate(LocalDateTime.now());List<CourseBase> courseBases = new ArrayList();courseBases.add(courseBase);PageResult pageResult = new PageResult<CourseBase>(courseBases,10,1,10);return pageResult;}

观察swagger界面，结果可以正常返回

查看全文

http://www.lryc.cn/news/31875.html