SpringBoot整合Swagger学习

最新推荐文章于 2025-04-01 14:43:20 发布

HISS-XW

最新推荐文章于 2025-04-01 14:43:20 发布

阅读量228

点赞数 2

分类专栏： SpringBoot Swagger 文章标签： SpringBoot整合Swagger学习

本文链接：https://blog.youkuaiyun.com/qq_42352175/article/details/88088739

版权

SpringBoot 同时被 2 个专栏收录

2 篇文章

订阅专栏

Swagger

1 篇文章

订阅专栏

本文介绍Swagger，一种用于RESTful Web服务的规范和框架，能自动生成接口文档，简化前端与后端的交流，支持在线测试接口。涵盖Swagger的主要作用、解决的手写API文档痛点及如何在SpringBoot中整合Swagger2生成文档。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

什么是Swagger？

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

官网：https://swagger.io/

主要作用

接口的文档在线自动生成
功能测试

手写Api文档的几个痛点：

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

Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

其他的不多说，想要了解Swagger的，可以去Swagger官网，可以直接使用Swagger editor编写接口文档，当然我们这里讲解的是SpringBoot整合Swagger2，直接生成接口文档的方式。

Swagger的开源项目

Swagger-tools：提供各种与Swagger进行集成和交互的工具
Swagger-core：用于Java/Scala的的Swagger实现
Swagger-js: 用于JavaScript的Swagger实现
Swagger-node-express: Swagger模块，用于node.js的Express web应用框架
Swagger Editor：基于浏览器的编辑器，您可以在其中编写OpenAPI规范
Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档
Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码

SpringBoot+Swagger

不会springBoot请看：

添加swagger依赖

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.7.1.RELEASE</version>
</dependency>

配置swagger

配置文件配置：

#swagger页面标题
swagger.title=spring-boot-&-Swagger2
#swagger页面链接模块标题
swagger.description=Link info
#swagger标题上的版本号
swagger.version=1.0
#链接信息：显示名称
swagger.contact.name=login application
#链接信息：链接地址
swagger.contact.url=http://localhost:8080/login
#扫描包路径下的API注解生成API信息（自己创建的controller包路径）
swagger.base-package=com.springboot.web.controller

使用配置类：

@Configuration
  @EnableSwagger2Doc
  public class AddResource {
    @Bean
    public Docket createRestApi() {
        // 创建API页面展示信息
        ApiInfo apiInfo = new ApiInfoBuilder()
        // 页面标题 swagger-ui.html的标题
        .title("SpringBoot整合Swagger2")
        // 描述下的链接信息
        .contact(new Contact("Loyal", "http://localhost:8080/login", ""))
        // 版本号  页面标题上显示的版本号
        .version("1.0")
        // 页面API文档的描述信息
        .description("API 描述").build();

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(
                        // 将包路径下所有方法扫描成API
                        RequestHandlerSelectors.basePackage("com.springboot.web.controller")
                      )
                .paths(PathSelectors.any())
                .build();
    }

  }

注解配置API文档内容

@Api("Swagger 耍耍水")
  @RestController
  public class LoginController {

    Logger logger = LoggerFactory.getLogger(LoginController.class);

    @Autowired
      private MessageSource messageSource;
    // 定义API描述信息
    @ApiOperation(value="登录",notes="用户登录系统")
      // 定义API参数
    @ApiImplicitParams({
        @ApiImplicitParam(name="name",paramType="query",dataType="String",value="用户名",required=true),
        @ApiImplicitParam(name="pwd",paramType="query",dataType="String",value="密码",required=true)
    })
      @ApiResponses({
        @ApiResponse(code=200,message="请求成功了哦！"),
        @ApiResponse(code=404,message="页面去哪了？")
    })
    @RequestMapping("/login")
    public Map<String,Object> login(String name,String pwd) {
        logger.info("LoginController.login()===");
        Map<String,Object> model = new HashMap<String,Object>();
        model.put("resultCode", "success");
        model.put("resultMsg", "Operation success!");
        return model;
    }

      @ApiOperation(value="Test測試",notes="API測試耍耍！")
    @RequestMapping(value="/test",method=RequestMethod.POST)
    @ApiParam(name="用户对象",value="传入json格式",required=true)
    public String test(@RequestBody User user) {
        System.out.println("UserController.test()");
        return "success";
    }
  }

实体类注解

@ApiModel(value = "User", description = "用户信息描述")
  public class User {
      /**
       * 学号
       */
      @ApiModelProperty("证件号")
      private int    id;
      /**
       * 姓名
       */
      @ApiModelProperty("姓名")
      private String name;
      /**
       * 年龄
       */
      @ApiModelProperty("年龄")
      private int    age;
      /**
       * 性别
       */
      @ApiModelProperty("性别")
      private String sex;
      /**
       * 住址
       */
      @ApiModelProperty("家庭住址")
      private String address;
  }

访问路径：http://localhost:8080/swagger-ui.html