SpringBoot整合Swagger

最新推荐文章于 2025-05-12 09:00:00 发布
转载 最新推荐文章于 2025-05-12 09:00:00 发布 · 279 阅读 · 0

本文介绍如何在SpringBoot项目中整合Swagger，实现API文档的自动生成和在线测试，解决传统文档更新不及时、接口返回结果不明确等问题。通过配置依赖、Swagger配置类和使用相关注解，可以轻松管理和维护API文档。

SpringBoot整合Swagger

Swagger能解决手写API文档的几个痛点：

  1. 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
  2. 接口返回结果不明确
  3. 不能直接在线测试接口，通常需要使用工具，比如postman
  4. 接口文档太多，不好管理

一、依赖

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

二、Swagger配置类

其实这个配置类，只要了解具体能配置哪些东西就好了，毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径，不然生成的文档扫描不到接口。

package cn.saytime;
​
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
​
/**
 * @author zh
 * @ClassName cn.saytime.Swgger2
 * @Description
 * @date 2017-07-10 22:12:31
 */
@Configuration
public class Swagger2 {
​
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 扫描的包所在位置
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                // 扫描的 URL 规则
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格，http://blog.youkuaiyun.com/saytime")
                .termsOfServiceUrl("http://blog.youkuaiyun.com/saytime")
                .version("1.0")
                .build();
    }
}

用@Configuration注解该类，等价于XML中配置beans；用@Bean标注方法等价于XML中配置bean。

Application.class 加上注解@EnableSwagger2 表示开启Swagger

package cn.saytime;
​
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
​
@SpringBootApplication
@EnableSwagger2
public class SpringbootSwagger2Application {
​
    public static void main(String[] args) {
        SpringApplication.run(SpringbootSwagger2Application.class, args);
    }
}

三、Restful 接口

package cn.saytime.web;
​
import cn.saytime.bean.JsonResult;
import cn.saytime.bean.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
​
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
​
/**
 * @author zh
 * @ClassName cn.saytime.web.UserController
 * @Description
 */
@RestController
public class UserController {
​
    // 创建线程安全的Map
    static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer, User>());
​
    /**
     * 根据ID查询用户
     * @param id
     * @return
     */
    @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
    @RequestMapping(value = "user/{id}", method = RequestMethod.GET)
    public ResponseEntity<JsonResult> getUserById (@PathVariable(value = "id") Integer id){
        JsonResult r = new JsonResult();
        try {
            User user = users.get(id);
            r.setResult(user);
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }
​
    /**
     * 查询用户列表
     * @return
     */
    @ApiOperation(value="获取用户列表", notes="获取用户列表")
    @RequestMapping(value = "users", method = RequestMethod.GET)
    public ResponseEntity<JsonResult> getUserList (){
        JsonResult r = new JsonResult();
        try {
            List<User> userList = new ArrayList<User>(users.values());
            r.setResult(userList);
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }
​
    /**
     * 添加用户
     * @param user
     * @return
     */
    @ApiOperation(value="创建用户", notes="根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    @RequestMapping(value = "user", method = RequestMethod.POST)
    public ResponseEntity<JsonResult> add (@RequestBody User user){
        JsonResult r = new JsonResult();
        try {
            users.put(user.getId(), user);
            r.setResult(user.getId());
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");
​
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }
​
    /**
     * 根据id删除用户
     * @param id
     * @return
     */
    @ApiOperation(value="删除用户", notes="根据url的id来指定删除用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    @RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
    public ResponseEntity<JsonResult> delete (@PathVariable(value = "id") Integer id){
        JsonResult r = new JsonResult();
        try {
            users.remove(id);
            r.setResult(id);
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");
​
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }
​
    /**
     * 根据id修改用户信息
     * @param user
     * @return
     */
    @ApiOperation(value="更新信息", notes="根据url的id来指定更新用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
    })
    @RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
    public ResponseEntity<JsonResult> update (@PathVariable("id") Integer id, @RequestBody User user){
        JsonResult r = new JsonResult();
        try {
            User u = users.get(id);
            u.setUsername(user.getUsername());
            u.setAge(user.getAge());
            users.put(id, u);
            r.setResult(u);
            r.setStatus("ok");
        } catch (Exception e) {
            r.setResult(e.getClass().getName() + ":" + e.getMessage());
            r.setStatus("error");
​
            e.printStackTrace();
        }
        return ResponseEntity.ok(r);
    }
​
    @ApiIgnore//使用该注解忽略这个API
    @RequestMapping(value = "/hi", method = RequestMethod.GET)
    public String  jsonTest() {
        return " hi you!";
    }
}

Json格式输出类 JsonResult.class

package cn.saytime.bean;
​
public class JsonResult {
​
    private String status = null;
​
    private Object result = null;
​
    // Getter Setter
}

实体User.class

package cn.saytime.bean;
​
import java.util.Date;
​
/**
 * @author zh
 * @ClassName cn.saytime.bean.User
 * @Description
 */
public class User {
​
    private int id;
    private String username;
    private int age;
    private Date ctm;
​
    // Getter Setter
}

项目结构：

https://i-blog.csdnimg.cn/blog_migrate/809857a65b392bc71f6069fe8d40d8ea.png

四、Swagger2文档

启动SpringBoot项目，访问 http://localhost:8080/swagger-ui.html

https://i-blog.csdnimg.cn/blog_migrate/08dc3cbdc5a73c0a3df53ae6a9d2ba28.png

五、Swagger注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

  • @Api：修饰整个类，描述Controller的作用
  • @ApiOperation：描述一个类的一个方法，或者说一个接口
  • @ApiParam：单个参数描述
  • @ApiModel：用对象来接收参数
  • @ApiProperty：用对象接收参数时，描述对象的一个字段
  • @ApiResponse：HTTP响应其中1个描述
  • @ApiResponses：HTTP响应整体描述
  • @ApiIgnore：使用该注解忽略这个API
  • @ApiError ：发生错误返回的信息
  • @ApiImplicitParam：一个请求参数
  • @ApiImplicitParams：多个请求参数
@ApiOperation(value = "更新xxxxxx", notes = "根据xxxxxx更新xxxxxx")
@ApiImplicitParam(name = "xxxxxx", value = "订单xxxxxx实体", required = true, dataType = "xxxxxx")



@ApiOperation(value = "更新xxxxxx状态以及支付相关的方式及状态", notes = "根据xxxxxx更新xxxxxx")
	@ApiImplicitParams({
			@ApiImplicitParam(name = "xxxxxx", value = "机票订单号", required = true, dataType = "String"),
			@ApiImplicitParam(name = "status", value = "ProductAir状态", required = true, dataType = "int"),
			@ApiImplicitParam(name = "xxxxxx", value = "订单支付状态", required = false, dataType = "Integer"),
			@ApiImplicitParam(name = "xxxxxxType", value = "订单支付方式", required = false, dataType = "Integer") })

 

springBoot整合Swagger项目例子
01-22
SpringBoot整合Swagger项目是一个实用的例子，它展示了如何在SpringBoot应用程序中集成Swagger，以便于创建API文档和进行接口测试。Swagger是一个强大的工具，用于设计、构建、文档化和使用RESTful Web服务。在这个...
springboot整合swagger2实例
02-28
SpringBoot整合Swagger2实例详解 在现代Web开发中，API文档的重要性不言而喻，它为开发者提供了清晰的接口说明，使得开发、测试和维护工作更加高效。Swagger2是一款流行的API文档工具，它能自动生成RESTful API的...
spring boot 集成 swagger3
Mr_Dong_cson的博客
05-24 3579
Swagger 3是一种开源的API描述工具，它可以帮助开发人员设计、构建、文档化和测试API。Swagger 3支持多种编程语言和框架，包括Java、Node.js、Python、Ruby等，并提供了许多集成工具和插件，例如Postman、Apigee等。Swagger 3使用OpenAPI规范来描述API，这是一种通用的API描述语言，适用于各种编程语言和框架。OpenAPI规范定义了API的基本结构、请求和响应的参数、头部信息、路径、HTTP方法和安全方案等。
SpringBoot整合Swagger3.0使用及报错解决大全
7me
03-14 9039
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
Spring Boot整合Swagger2弹出提示Unable to infer base url.
Java精选
03-30 1266
Spring Boot整合Swagger2弹出提示Unable to infer base url. https://blog.yoodb.com/yoodb/article/detail/1581
SwaggerAPI注解详解,以及注解常用参数配置
热门推荐
都让你们叫老了的博客
01-29 7万+
官网github地址：https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X 注解 @Api： 作用在类上，用来标注该类具体实现内容。表示标识这个类是swagger的资源 。 参数： 1. tags：可以使用tags()允许您为操作设置多个标签的属性，而不是使用该属性。 2. descriptio...
springboot整合swagger
qq_67832732的博客
12-05 943
作为后端开放人员，最烦的事就是自己写接口文档和别人没有写接口文档，不管是前端还是后端开发，多多少少都会被接口文档所折磨，前端会抱怨后端没有及时更新接口文档，而后端又会觉得编写接口文档太过麻烦。Swagger 可以较好的解决接口文档的交互问题，以一套标准的规范定义接口以及相关的信息，就能做到生成各种格式的接口文档，生成多种语言和客户端和服务端的代码，以及在线接口调试页面等等。只需要更新 Swagger 描述文件，就能自动生成接口文档，做到前端、后端联调接口文档的及时性和便利性。
Springboot整合Swagger
m0_66403070的博客
09-11 377
Springboot整合Swagger
springboot整合swagger2
2403_87916407的博客
12-14 1616
Spring Boot 整合 Swagger2 的作用主要体现在以下几个方面：自动生成接口文档：Swagger2 能够根据 Spring Boot 项目中的代码自动生成 RESTful API 文档，减少了手动编写和维护 API 文档的工作量。提高开发效率：通过自动生成的文档，开发人员可以快速了解和测试各个 API 接口的功能和参数，提高了开发效率。减少沟通成本：在前后端分离的开发模式中，Swagger2 提供的在线文档可以减少前后端的沟通成本，帮助新加入项目的同事快速上手业务。
Springboot整合Swagger3
Java后端技术栈
05-11 267
SpringBoot 整合Swagger
逍遥人世欢
05-12 1296
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。是一套流行的 API 框架，可以帮助开发人员快速构建 API 文档，还可以方便测试项目各项功能。API 的两层意思帮助文档JDK API应用程序接口第三方支付支付宝接口。
SpringBoot整合Swagger3生成接口文档过程解析
08-18
SpringBoot整合Swagger3生成接口文档过程解析 SpringBoot整合Swagger3生成接口文档过程解析是当前项目中非常重要的一部分，在前后端分离的项目中，接口文档的存在十分重要。 Swagger是一个自动生成接口文档的工具...
springboot整合swagger2的demo.zip
03-10
.title("Spring Boot整合Swagger2示例") .description("这是一个使用Spring Boot和Swagger2构建的RESTful API") .version("1.0.0") .license("Apache 2.0") .licenseUrl(...
【C、C#】基于 51 单片机与 RC522 的智能门禁系统（解决便捷安全与开锁慢问题）.zip
12-31
【C、C#】基于 51 单片机与 RC522 的智能门禁系统（解决便捷安全与开锁慢问题）.zip
AI时代，中小技术转移机构面临营收增长承压挑战，如何抓住新一代成果转化SaaS机遇实现成果转化成功率？.docx
12-31
AI时代，中小技术转移机构面临营收增长承压挑战，如何抓住新一代成果转化SaaS机遇实现成果转化成功率？
软件开发-UT模板(docker一键部署)
12-31
针对项目代码为C/C++语言编写的UT模板，测试工具为google test，采用docker环境，可一键部署使用。模板中设计了一个计算器项目作为案例，浅显易懂。
microservices-on-k8s
12-31
基于springcloud的微服务在k8s上的CICD的例子，包括基础环境部署（mysql、redis等）和微服务部署
vue2.0组件间通信方法
最新发布
12-31
代码转载自：https://pan.quark.cn/s/c2b80d54caad Vue.js 是一种广受欢迎的前端开发框架，其用途在于构建用户交互界面。 在 Vue 2.0 版本中，组件之间的信息交互是其关键特性之一，它保障了应用数据流向的顺畅性。 本资料将详尽阐述 Vue 2.0 中涉及父子组件以及非直接关联组件之间的通信途径。 1. **由父级组件向子级组件传输数据** 在 Vue 框架中，父级组件向子级组件传输数据的主要途径是通过 `props` 属性。 以下提供一个基础的范例： 父级组件（Parent）： ```html <parent> <child :child-msg="msg"></child> </parent> <script> export default { data() { return { msg: [1, 2, 3] }; } }; </script> ``` 子级组件（Child）： ```javascript export default { props: [childMsg], // 或者 props: { childMsg: Array // 指定输入数据类型，若不正确将引发警告 // 或者 childMsg: { type: Array, default: [0, 0, 0] // 设定默认值 } } }; ``` 通过这种方式，父级组件中的数据 `msg` 可以经由 `props` 传递给子级组件，并在子级组件内部加以运用。 2. **子级组件与父级组件之间的信息交换** Vue 2.0 遵循单向数据流动原则，即子级组件无法直接更动父级组件的数据。 然而，可以通过引发自定义事件来提示父级组件进行数据更新。 例如： 子级组件（Ch...
SpringBoot整合swagger
12-10
Spring Boot 整合 Swagger 的详细教程如下： ### 安装 Swagger 先下载 Swagger，然后完成安装操作，不过引用中未提及具体的下载和安装步骤，一般在 Spring Boot 项目里可通过在 `pom.xml` 中添加 Swagger 相关依赖来完成安装，例如添加 Swagger2 和 Swagger UI 的依赖： ```xml <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> ``` ### 使用 Swagger 1. **编写接口**：在 Spring Boot 项目里编写 RESTful 接口，示例代码如下： ```java import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/api") public class HelloController { @GetMapping("/hello") public String hello() { return "Hello, Swagger!"; } } ``` 2. **启用 Swagger**：创建一个配置类来启用 Swagger，示例代码如下： ```java 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.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) .paths(PathSelectors.any()) .build() .apiInfo(apiInfo()); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot Swagger API") .description("API documentation for Spring Boot application") .version("1.0.0") .build(); } } ``` 3. **查看接口文档**：启动 Spring Boot 项目，在浏览器中访问 `http://localhost:8080/swagger-ui.html`（如果使用 Swagger2） 或者 `http://localhost:8080/doc.html`（如果使用 Swagger BootstrapUI），就能查看生成的接口文档 [^2]。 ### 高级使用 1. **描述数据模型**：借助 Swagger 的注解（如 `@ApiModel` 和 `@ApiModelProperty`）来描述数据模型，示例代码如下： ```java import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; @ApiModel(description = "User model") public class User { @ApiModelProperty(value = "User ID", example = "1") private Long id; @ApiModelProperty(value = "User name", example = "John Doe") private String name; // Getters and setters } ``` 2. **描述枚举类型**：使用 `@ApiModel` 和 `@ApiModelProperty` 注解描述枚举类型，示例代码如下： ```java import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; @ApiModel(description = "User role") public enum UserRole { @ApiModelProperty(value = "Admin role") ADMIN, @ApiModelProperty(value = "User role") USER } ``` 3. **描述响应参数**：使用 `@ApiResponse` 注解描述响应参数，示例代码如下： ```java import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiResponse; import io.swagger.annotations.ApiResponses; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @Api(tags = "User API") @RestController @RequestMapping("/api/users") public class UserController { @ApiOperation(value = "Get user by ID") @ApiResponses(value = { @ApiResponse(code = 200, message = "Success", response = User.class), @ApiResponse(code = 404, message = "User not found") }) @GetMapping("/{id}") public User getUserById(Long id) { // Implementation return null; } } ``` ### 进阶使用 1. **配置全局参数**：若使用 Swagger BootstrapUI，可在“文档管理”中增加全局参数，包含添加 header 参数 [^3]。 2. **配置安全协议**：可在 Swagger 中配置安全协议，如 OAuth2 等。 3. **配置安全上下文**：配置安全上下文以确保接口的安全性。 4. **配置忽略参数**：配置忽略某些不需要显示的参数。 ### 整合 Spring Security 时的注意事项 在 Spring Boot 整合 Spring Security 和 Swagger 时，需要配置拦截的路径和放行的路径，要放行以下几个路径： ```java .antMatchers("/swagger**/**").permitAll() .antMatchers("/webjars/**").permitAll() .antMatchers("/v2/**").permitAll() .antMatchers("/doc.html").permitAll() ``` 如果使用了 bootstarp 的 Swagger UI 界面，需添加最后一个路径 [^1]。
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
红包 添加红包
表情包 插入表情
表情包 代码片
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值