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

【swagger】Swagger的简单使用

news 来源：原创 2025/6/27 10:24:36

Swagger是一套基于OpenAPI规范的开源工具集，用于设计、构建、文档化和测试RESTful API。它通过代码注解自动生成实时更新的交互式API文档（如Swagger UI），支持在线调试接口，并提供跨语言支持（如Java、Python）。核心组件包括Swagger Editor（API设计）、Swagger Codegen（代码生成），能显著提升团队协作效率，减少前后端沟通成本，是API全生命周期管理的标准化解决方案。

Swagger是一个框架，可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。

光有文档还不够，Swagger生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

名词解释

OpenAPI：由Linux基金会维护的RESTful API描述规范标准（前身是Swagger规范）。

Swagger：基于OpenAPI规范的具体实现版本，提供API文档生成工具和注解体系。

SpringFox：非官方Spring社区项目，将Swagger集成到Spring生态的工具库。

引入依赖

在pom.xml中引入springfox库：

<?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-demo</artifactId><version>1.0-SNAPSHOT</version><properties><maven.compiler.source>8</maven.compiler.source><maven.compiler.target>8</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding><java.version>8</java.version></properties><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version></dependency></dependencies><dependencyManagement><dependencies><!-- spring boot 依赖 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-dependencies</artifactId><version>2.3.4.RELEASE</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement></project>

初步演示

浏览器输入：http://localhost:8080/swagger-ui/index.html

可以看到页面上的信息都是默认的，还有很多/error的接口注释。

配置Docket实例

创建配置类定义API文档信息、扫描范围及分组：

package com.morris.swagger.demo.single;import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;@Configuration
public class SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo()).select()// 扫描@ApiOperation.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 排除/error路径.paths(PathSelectors.regex("(?!/error.*).*")).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Swagger API").description("this is a description").termsOfServiceUrl("http://springfox.io").contact(new Contact("springfox", "https://morris131.github.io", "morris131@163.com")).license("Apache License Version 2.0").licenseUrl("https://github.com/springfox/springfox/blob/master/LICENSE").version("3.0").build();}}

注解的使用

控制器层

@Api(tags = “user相关接口”)：类注解，定义模块名称。
@ApiOperation(“user列表”)：方法注解，描述接口功能。
@ApiParam(“用户ID”)：参数注解，说明参数意义。

package com.morris.swagger.demo.single;import com.morris.swagger.vo.R;
import com.morris.swagger.vo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;@RestController
@RequestMapping("user")
@Api(tags = "用户相关接口")
public class UserController {@GetMapping("get")@ApiOperation("查询用户")public R<User> getById(@ApiParam("用户ID") Long userId) {return R.ok(new User(userId, "morris", 18));}@PostMapping("save")@ApiOperation("保存用户")public R<Void> save(@RequestBody User user) {return R.ok();}
}

实体类层

@ApiModel(value = “用户”, description = “用户实体类”)：类注解。
@ApiModelProperty(value = “用户ID”, required = true, example = “1”)：字段注解，需配合Getter方法生效。

package com.morris.swagger.vo;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "用户", description = "用户实体类")
public class User {@ApiModelProperty(value = "用户ID", required = true, example = "1")private Long id;@ApiModelProperty(value = "姓名", required = true, example = "morris")private String name;@ApiModelProperty(value = "年龄", required = true, example = "21")private Integer age;
}