SpringBoot整合Swagger

本文介绍如何在SpringBoot项目中集成Swagger,实现RESTful接口文档的自动生成与测试功能。通过详细步骤指导如何添加依赖、配置Swagger并编写Controller。

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

1、什么是Swagger

      Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。
      Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
      Swagger的目标是为REST APIs 定义一个标准的,与语言无关的接口,使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义,消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口,Swagger去掉了调用服务时的很多猜测。

2、为什么要使用Swagger

      想想我们之前在项目中的接口,通常都要给每个接口写对应的接口文档,如果项目中的接口都是内部使用并且开发团队都在一起,也许可以省掉写接口文档,开发一个新的接口直接口头表述,后面自己去看这些接口都不知道是干什么用,更别说接口给外部团队使用了。之前编写接口文档可能都是用Word文档写或者用javadoc注释生成文档。两种都比较麻烦,手写耗时耗力,生成文档每次都要编译一遍。使用Swagger则可以快速的生成文档。

3、使用Swagger的好处

  • 前后端分离开发
  • API文档非常明确
  • 测试的时候不需要再使用URL输入浏览器的方式来访问Controller
  • 传统的输入URL的测试方式对于post请求的传参比较麻烦(当然,可以使用postman这样的浏览器插件)
  • Swagger与SpringBoot的集成简单

4、将Swagger与SpringBoot集成

4.1 添加依赖

在项目的pom.xml添加swagger依赖,这里就不介绍SpringBoot依赖添加了。

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

4.2 创建Swagger配置类

/**
 * Swagger2启动类
 * Created by Arvin on 2017/12/7.
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    /**
     * 创建用户API文档
     * @return
     */
    @Bean
    public Docket createRestUserApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                   .groupName("user")
                .apiInfo(createUserApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.tenghu.swa.user"))
                .paths(PathSelectors.any())
                .build();

    }

    /**
     * 创建客户API文档
     * @return
     */
    @Bean
    public Docket createRestCusApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("cus")
                .apiInfo(createCusApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.tenghu.swa.cus"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建用户API信息
     * @return
     */
    private ApiInfo createUserApiInfo(){
        return new ApiInfoBuilder()
                .title("处理用户信息相关接口")
                .description("以下接口只操作用户信息")
                .contact(new Contact("Arvin","http://blog.youkuaiyun.com/tenghu8888","libiaohu@126.com"))
                .version("1.0")
                .build();
    }

    /**
     * 创建客户API信息
     * @return
     */
    private ApiInfo createCusApiInfo(){
        return new ApiInfoBuilder()
                .title("处理客户信息相关接口")
                .description("以下接口只操作客户信息")
                .contact(new Contact("Arvin","http://blog.youkuaiyun.com/tenghu8888","libiaohu@126.com"))
                .version("1.0")
                .build();
    }
}

      创建Swagger配置类时,类名随意创建,但是类上面必须添加@Configuration、@EnableSwagger2这两个注解,通过@Configuration注解,让Spring来加载该类配置,@EnableSwagger2注解来启用Swagger2。再通过被@Bean注解的函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,本例采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore注解的API)。这里如果函数上面不配置@Bean,那么Swagger只是启动了,没有创建API信息。
      从上面配置类中可以创建多个函数并用@Bean注解,这样就可以针对不同的Controller创建出各自的API文档。

需要注意的是:在创建多个API时,需要指定API文档的名称。groupName(),如果不指定在项目启动的时候就会报错。

4.3 编写Controller

      在这里编写自己的RESTFull风格的接口,跟正常开发没什么区别,只是要在对应的类、函数、参数上加上Swagger注解就可以了。注解说明:
1. @Api:用在类上,说明该类的作用
2. @ApiOperation:用在方法上,说明方法的作用
3. @ApiImplicitParams:用在方法上包含一组参数说明
4. @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
      paramType:参数放在哪个地方
         header请求参数的获取:@RequestHeader
         query请求参数的获取:@RequestParam
         path(用于restful接口)–>请求参数的获取:@PathVariable
         body(不常用)
         form(不常用)
      name:参数名
      dataType:参数类型
      required:参数是否必须传
      value:参数的意思
      defaultValue:参数的默认值
5. @ApiResponses:用于表示一组响应
6. @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
      code:数字,例如400
      message:信息,例如”请求参数没填好”
      response:抛出异常的类
7. @ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
8. @ApiModelProperty:描述一个model的属性
9. @ApiIgnore:生成文档时忽略

具体其他注解及详细解释查看:
https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

/**
 * Created by Arvin on 2017/12/7.
 */

@RestController
@RequestMapping(value = "/cus")
@Api(value = "客户服务接口",description = "提供对客户操作服务接口(增、删、改、查)用户信息")
public class CusController {
    private static List<Customer> customerList=new ArrayList<Customer>();

    static {
        customerList.add(new Customer("1","G00001","广州视源股份有限公司","CVTE","广州市黄埔区云埔6号"));
        customerList.add(new Customer("2","G00002","广州赛意信息科技股份有限公司","SIE","佛山市顺德区北滘镇新城区怡和路怡和中心11楼"));
    }

    @RequestMapping(value = "/all",method = RequestMethod.GET)
    @ApiOperation(value = "获取所有客户信息",notes = "获取当前所有有效客户信息")
    public List<Customer> getAllCustomer(){
       return customerList;
    }

    @RequestMapping(value = "/get/{cusId}",method = RequestMethod.GET)
    @ApiOperation(value = "根据客户ID获取客户信息",notes = "根据客户ID获取客户信息")
    @ApiImplicitParam(paramType = "path",name = "cusId",required = true,value = "客户ID",dataType = "string")
    public Customer getCusById(@PathVariable("cusId") String cusId){
        for (Customer customer:customerList){
            if(cusId.equals(customer.getCusId())){
                return customer;
            }
        }
        return null;
    }


    @RequestMapping(value = "/save",method = RequestMethod.POST)
    @ApiOperation(value = "保存客户信息",notes = "保存客户信息",httpMethod = "POST")
    public List<Customer> saveCus(
            @ApiParam(name = "customer",required = true,type = "object",value = "客户信息")
                    Customer customer){
        customerList.add(customer);
        return customerList;
    }

    @RequestMapping(value = "/del/{cusId}",method = RequestMethod.GET)
    @ApiOperation(value = "刪除客戶信息",notes = "根据客户ID删除客户信息")
    @ApiImplicitParam(value = "客户ID",name = "cusId",paramType = "path",required = true)
    public List<Customer>  deleteCus(@PathVariable("cusId") String cusId){
                for (Customer customer:customerList){
                    if (cusId.equals(customer.getCusId())){
                        customerList.remove(customer);
                    }
                }
        return customerList;
    }
}

这里只贴出一个Controller代码,其他Controler一样的写法。

4.4 编写SpringBoot启动类

@ComponentScan({"com.tenghu.ws"})
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

完成以上代码,启动SpringBoot后,在浏览器输入http://127.0.0.1:8091/note/swagger-ui.html 就可以看到一下界面。
这里写图片描述
这里写图片描述
上面有提到过在Swagger里面创建了两个API,在界面就可以看到两个API的选项,如下:
这里写图片描述

5、源码下载

完整结果实例可查看:SpringBoot-Swagger

<think>好的,我现在需要帮助用户了解如何在Spring Boot项目中集成Swagger来生成API文档。根据用户提供的引用内容,我需要整理出一个清晰的步骤指南,同时确保遵循系统级指令,比如正确使用LaTeX格式和生成相关问题。 首先,我需要回顾用户提供的引用内容。引用[1]介绍了Spring Boot和Swagger的基本概念,以及整合的必要性。引用[3]提到了准备工作,比如JDK版本、IDE、构建工具和所需依赖。引用[5]提到了依赖版本的问题,特别是Spring Boot与Swagger版本的兼容性。引用[2]和[4]则涉及配置类中的注解以及如何在生产环境禁用Swagger。 接下来,我需要组织这些信息,按照步骤说明整合过程。第一步应该是创建Spring Boot项目,然后添加Swagger依赖。这里需要注意版本兼容性,比如引用[5]提到的使用2.9.2版本的springfox-swagger2和springfox-swagger-ui。然后,配置Swagger,创建配置类,添加必要的注解如@Configuration、@EnableSwagger2,可能还有@EnableSwaggerBootstrapUI(引用[2])。接着,配置API文档的基本信息,如标题、描述、版本等,这通常在Docket bean中设置。 还需要考虑生产环境的安全措施,如引用[4]提到的使用@Profile限制环境,或者整合权限管理。这部分可能需要简要提及,但用户的问题主要集中在配置方法,所以重点在配置步骤。 同时,我需要确保所有行内数学表达式正确使用$...$格式,但这里可能涉及较少数学内容,不过如果有版本号或其他代码内的变量,可能需要处理。例如,Maven依赖中的版本号可能需要用行内代码块而非LaTeX,但根据示例,代码部分应该用代码块包裹,所以可能不需要LaTeX处理。 检查是否有需要单独成段的公式,但问题主要涉及配置步骤和代码,可能不需要独立公式。确保使用中文回答,结构清晰,分步骤说明,每个步骤有代码示例或配置示例。 最后,生成相关问题,根据用户提供的引用内容,可能涉及版本兼容性、生产环境配置、UI增强、权限管理整合等。 现在整理步骤: 1. 创建Spring Boot项目:使用IDE或Spring Initializr,确保JDK8+,Maven/Gradle。 2. 添加Swagger依赖:根据引用[5],添加springfox-swagger2和springfox-swagger-ui的2.9.2版本。 3. 创建Swagger配置类:使用@Configuration和@EnableSwagger2注解,可能包括@EnableSwaggerBootstrapUI(引用[2])。 4. 配置Docket Bean:设置API信息,扫描的包路径等。 5. 访问Swagger UI:运行项目后通过特定URL访问。 6. 生产环境配置:使用@Profile限制环境(引用[4])。 在回答中需要引用对应的引用来源,如配置类中的注解引用[2],环境配置引用[4],依赖版本引用[5]等。 现在检查是否有遗漏或错误,比如版本兼容性问题,确保代码示例正确,特别是配置类和依赖部分。确认所有引用正确标注,问题部分涵盖用户可能关心的其他方面,如优化、安全、版本问题等。</think>### Spring Boot 整合 Swagger 配置方法及教程 #### **1. 创建 Spring Boot 项目** - 使用 **Spring Initializr** 或 IDE(如 IntelliJ IDEA)创建项目,选择 **Maven/Gradle** 作为构建工具。 - 确保 JDK 版本为 **8 及以上**,并添加 Spring Web 依赖[^3]。 #### **2. 添加 Swagger 依赖** 在 `pom.xml` 中添加以下依赖(注意版本兼容性[^5]): ```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> ``` #### **3. 创建 Swagger 配置类** 新建配置类 `SwaggerConfig.java`,添加注解并配置 API 信息[^2][^4]: ```java @Configuration @EnableSwagger2 @EnableSwaggerBootstrapUI // 可选:增强UI界面 @Profile({"dev", "test"}) // 仅在开发/测试环境启用 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 扫描的包路径 .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("API 文档") .description("接口说明") .version("1.0") .build(); } } ``` #### **4. 配置生产环境禁用 Swagger** 在 `application.properties` 中设置环境为 `prod`[^4]: ```properties spring.profiles.active=prod ``` #### **5. 访问 Swagger UI** 启动项目后,通过以下 URL 访问: - 默认 UI:`http://localhost:8080/swagger-ui.html` - 增强 UI(需添加 `@EnableSwaggerBootstrapUI`):`http://localhost:8080/doc.html` --- ### **关键配置说明** | 配置项 | 说明 | |-------------------------|--------------------------------------------------------------------| | `@EnableSwagger2` | 启用 Swagger 核心功能 | | `RequestHandlerSelectors` | 指定扫描的 Controller 包路径 | | `@Profile({"dev","test"})` | 限制 Swagger 仅在开发/测试环境生效 | ---
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

小老虎Love

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

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

余额充值