Idea创建spring boot 项目(2)整合Swagger

最新推荐文章于 2025-07-07 18:42:17 发布

原创最新推荐文章于 2025-07-07 18:42:17 发布 · 2.4k 阅读

2 ·

CC 4.0 BY-SA版权

文章标签：

#spring boot #swagger #idea #gradle #swagger 2.7.0

spring boot 专栏收录该内容

4 篇文章

订阅专栏

本文介绍如何在SpringBoot项目中集成Swagger，实现API文档自动生成和接口测试功能。包括项目搭建步骤、Swagger配置及控制器注解示例。

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

接博客--->Idea创建spring boot 项目(1)

使用工具：

IDE：idea 2017.2.6

spring boot 版本：1.5.9

构建工具：gradle

Swagger版本：Swagger 2.7.0

1、项目工程原结构如下：三处红框需要修改的

2、修改后如下图：

（1）修改了包名com.demo.demo--->com.demo;

（2）修改了启动类名DemoApplicatioin--->App;

（3）删除了test及其以下的包；

ps:个人习惯

3、Swagger简述：

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

Swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiParamImplicitL：一个请求参数
@ApiParamsImplicit 多个请求参数

4、修改后的项目的build.gradle文件：

（注意引用的中央仓库仓库是阿里云的仓库,Swagger的版本是2.7.0）

buildscript {
   ext {
      springBootVersion = '1.5.9.RELEASE'//spring boot 版本
   }
   repositories {
      mavenCentral()
   }
   dependencies {
      classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
   }
}


//添加资源库
repositories {
   maven { url 'http://maven.aliyun.com/nexus/content/repositories/central' }//添加阿里仓库
   mavenCentral()//添加Maven中央资源库
}


apply plugin: 'java'// 指定项目为java项目，项目编译(在项目提示符下执行：gradle build)时生成项目的jar包。
apply plugin: 'eclipse'
apply plugin: 'idea'
apply plugin: 'spring-boot'
apply plugin: 'application'

group = 'com.demo'
version = '1.5.9-SNAPSHOT'
sourceCompatibility = 1.8
targetCompatibility = 1.8

mainClassName = 'com.tinckay.App'//告诉gradle启动类的路径

dependencies {

   compile("org.springframework.boot:spring-boot-starter-web")

   testCompile("org.springframework.boot:spring-boot-starter-test")

   compile("org.springframework.boot:spring-boot-starter-tomcat")
   
   compile("io.springfox:springfox-swagger2:2.7.0")//swagger2核心依赖
   compile("io.springfox:springfox-swagger-ui:2.7.0")//为项目提供api展示及测试的界面

}

5、在项目启动类“App”同级包目录下建一个Swagger启动类“Swagger2”如下：

package com.demo;

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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author SAM
 * @create 2018-03-14 上午9:48
 **/

/** 通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。 */
@EnableSwagger2
@Configuration
public class Swagger2 {
    
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Spring boot Demo")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.demo.controller"))// 扫描的包所在位置
                .paths(PathSelectors.any()) // 扫描的 URL 规则
                .build();
    }
    
    private ApiInfo apiInfo() {
        Contact contact = new Contact("Spring Boot Demo", "localhost:98765/swagger-ui.html", "17520098152@163.com"); // 联系信息
        return new ApiInfoBuilder()
                .title("Spring boot 演示项目") // 大标题
                .description("Spring boot 演示项目") // 描述
                .termsOfServiceUrl("localhost:98765/swagger-ui.htm")// 服务条款 URL
                .contact(contact)
                .version("1.0.0-SNAPSHOT")// 版本
                .build();
    }
}

6、在com.demo包下创建一个controller包，在该包里创建一个演示用的DemoController，如下：

package com.demo.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author SAM
 * @create 2018-03-14 上午10:45
 **/

@Api(tags = "spring boot 演示接口")
@RestController
public class DemoController {

    @ApiOperation(value = "示例方法",notes = "这个方法的备注说明")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",value = "名字",required = true,paramType = "query",dataType = "String",defaultValue = "sam"),
            @ApiImplicitParam(name = "age",value = "年龄",required = false,paramType = "query",dataType = "int",defaultValue = "4")
    })
    @RequestMapping(value = "/demo", method = RequestMethod.POST)
    public String demo(@RequestParam String name,@RequestParam int age) {
        String result = "name is --->" +name+"   age is --->" +age;
        return result;
    }

    /**
     @Api：用在请求的类上，表示对类的说明
     tags="说明该类的作用，可以在UI界面上看到的注解"  
     value="该参数没什么意义，在UI界面上也看到，所以不需要配置"  

     @ApiOperation：用在请求的方法上，说明方法的用途、作用
     value="说明方法的用途、作用"  
     notes="方法的备注说明"  

     @ApiImplicitParams：用在请求的方法上，表示一组参数说明
     @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
     name：参数名  
     value：参数的汉字说明、解释  
     required：参数是否必须传  
     paramType：参数放在哪个地方  
     · header --> 请求参数的获取：@RequestHeader  
     · query --> 请求参数的获取：@RequestParam  
     · path（用于restful接口）--> 请求参数的获取：@PathVariable  
     · body（不常用）  
     · form（不常用）      
     dataType：参数类型，默认String，其它值dataType="Integer"         
     defaultValue：参数的默认值  

     @ApiResponses：用在请求的方法上，表示一组响应
     @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
     code：数字，例如400  
     message：信息，例如"请求参数没填好"  
     response：抛出异常的类  

     @ApiModel：用于响应类上，表示一个返回响应数据的信息
     （这种一般用在post创建的时候，使用@RequestBody这样的场景，  
     请求参数无法使用@ApiImplicitParam注解进行描述的时候）  
     @ApiModelProperty：用在属性上，描述响应类的属性

     */
    
}