springboot2.x集成swagger保姆级教程

最新推荐文章于 2025-05-01 23:24:04 发布

任冬9527

最新推荐文章于 2025-05-01 23:24:04 发布

阅读量782

点赞数 20

分类专栏： 1.编程语言 SpringBoot 文章标签： spring boot 接口隔离原则 java

本文链接：https://blog.csdn.net/qq_44959735/article/details/147635202

版权

1.编程语言同时被 2 个专栏收录

16 篇文章

订阅专栏

SpringBoot

8 篇文章

订阅专栏

1.概述

Swagger 是一款用于 API（应用程序接口）设计、开发、文档化及测试的工具框架，可简化 API 全生命周期管理。它通过标准化规范（OpenAPI）定义接口，自动生成交互式文档、客户端 / 服务端代码，支持在线调试，提升前后端协作效率，常见于 RESTful API 开发，核心工具包括 Swagger UI（可视化文档）、Swagger Editor（接口设计）等，让 API 开发更透明、高效。

1.1.以springboot为例，引入swagger依赖

<!-- swagger2 -->
<!-- 生成html文件的依赖 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
   
   <!-- 移除swagger-2.9.2版本的annotations、models，解决参数默认值会报错的bug -->
   <exclusions>
      <exclusion>
         <groupId>io.swagger</groupId>
         <artifactId>swagger-annotations</artifactId>
      </exclusion>
      <exclusion>
         <groupId>io.swagger</groupId>
         <artifactId>swagger-models</artifactId>
      </exclusion>
   </exclusions>
</dependency>

<!-- 提供在线测试的依赖 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

<!-- 自定义swagger版本 -->
<dependency>
   <groupId>io.swagger</groupId>
   <artifactId>swagger-annotations</artifactId>
   <version>1.5.21</version>
</dependency>
<dependency>
   <groupId>io.swagger</groupId>
   <artifactId>swagger-models</artifactId>
   <version>1.5.21</version>
</dependency>

1.2.编写swagger配置类

@ComponentScan("cn.test.swaggerdemo.controller") //扫描哪些包，需要生成在线文档
@EnableSwagger2  //必须要的注解
@EnableWebMvc    //必须要的注解
@Configuration
public class*SwaggerConfig {

    @Bean  //返回一个在线API文档，描述信息的配置对象
    public Docket commDucket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(this.apiInfo());
    }

    public ApiInfo apiInfo(){
        //在线文档的编写人信息
        Contact contact=new Contact("rd","www.1024xh.com","123@qq.com");

        //在线文档的描述信息
        return new ApiInfoBuilder()
                .title("swagger项目接口")
                .description("前台API接口")
                .contact(contact)
                .version("1.0.1")
                .build();

    }
}

1.3.配置在线文档的html文件路径

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
    
    //访问swagger-ui.html
    registry.addResourceHandler("swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/");

    //swagger-ui.html需要的css，js等文件的路径配置
    registry.addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

2.注解说明

2.1.实体类注解

@ApiModel()用于类；表示对类进行说明，用于参数用实体类接收

value–表示对象名

description–描述

都可省略

@ApiModelProperty()用于方法，字段；表示对model属性的说明或者数据操作更改

value–字段说明

name–重写属性名字

dataType–重写属性类型

required–是否必填

example–举例说明

hidden–隐藏

import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.io.Serializable;
import java.math.BigDecimal;



@ApiModel(value="PmsProduct",description="商品实体类")
@TableName("pms_product")
public class PmsProduct implements Serializable {
    private static final long serialVersionUID = 1L;


    / 主键ID /
    @TableId(value = "product_id")
    @ApiModelProperty(value = "唯一ID")
    private Long productId;

    / 商品封面 /
    @ApiModelProperty(value = "商品封面")
    private String cover;

}

2.2.请求层注解

配置了swagger的信息后，启动工程，访问项目下的 localhost:8080/swagger-ui.html，就可以看到扫描的接口层，所有接口信息，但是默认是没有提示信息的，需要使用一些注解，让在线文档更清晰

//当前模块的描述和详细描述
@Api(value = "StudentController",description = "学生管理页面的功能")  
@RestController
@RequestMapping("/student")
public class StudentController {

    List<Student> studentList=new ArrayList<>();

    public StudentController(){
        studentList.add(new Student(1,"tom"));
        studentList.add(new Student(2,"jack"));
    }


    //此API接口的描述和详细描述
    @ApiOperation(value = "添加功能",notes = "根据传入的学生信息添加到数据库")
   
    //此API需要的参数以及类型
    @ApiImplicitParam(value = "name",paramType = "query")//如果入参是表单参数，paramType改为query
    @RequestMapping(path = "/add",method = RequestMethod.POST)
    public Student addStudent(Student student){
        return student;
    }



    @ApiOperation(value = "删除功能",notes = "根据学生id删除该学生数据")
    @ApiImplicitParam(value = "id值",paramType = "path")//如果入参是url类型，paramType改为path
    @RequestMapping(path = "/del/{id}",method = RequestMethod.DELETE)
    public Student deleteStudent(@PathVariable("id") Integer id){
        Student student=new Student();
        student.setId(id);
        return student;
    }



    @ApiOperation(value = "修改功能",notes = "根据传入的学生信息进行修改")
    @ApiImplicitParam(value = "name",paramType = "body")//如果入参是json类型，paramType改为body
    @RequestMapping(path = "/edit",method = RequestMethod.PUT)
    public Student editStudent(Student student){
        return student;
    }




    @ApiOperation(value = "列表功能",notes = "查看当前模块的所有学生数据")
    @RequestMapping(path = "/list",method = RequestMethod.GET)
    public List<Student> list(){
        return studentList;
    }
}

注解说明：

类上的注解：@Api(tags = “FmsConsumeController”, description = “收支内容管理”)

方法的注解：

@ApiOperation(“添加一条收支记录”)

public CommonResult addConsume(Consume consume) {

方法的注解：

@ApiImplicitParam(value = “id值”,paramType = “query”)

@RequestMapping(path = “/add”, method = RequestMethod.POST)

public CommonResult addConsume(Consume consume) {

swagger兼容spring，会根据形参的字段自动转换成输入框，在页面上供测试

如果接口参数是json类型，在swagger网页调试时，只需在一个参数中填写json格式，把所有参数写到json体中调用即可。

3.页面访问测试

默认访问：http://localhost:8080/swagger-ui.html

4.配置自定义请求头

package com.yuchenboot.admin.system.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;



@ComponentScan("com.test.controller") //扫描哪些包，需要生成在线文档
@EnableSwagger2
@EnableWebMvc
@Configuration
public class Swagger2Configuration {

    @Bean
    public Docket commDucket(){

        //添加header参数token
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("x-access-token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        
        //所有的header参数构建完毕后，放入集合中
        pars.add(tokenPar.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .build()
                .globalOperationParameters(pars)//将要添加的header集合加入到构建器
                .apiInfo(this.apiInfo());
    }


    public ApiInfo apiInfo(){
        //在线文档的编写人信息
        Contact contact=new Contact("rd","www.1024xh.com","123@qq.com");

        //在线文档的描述信息
        return new ApiInfoBuilder()
                .title("rd-admin")
                .description("API接口文档")
                .version("1.0.0")
                .contact(contact)
                .build();

    }
}

5.配置全局请求头

在项目实际调试中，许多API都需要校验用户的token信息，swagger虽然可以自定义输入请求头，但是每次测试接口都需要输入，显得麻烦。swagger提供了一种全局认证的方式，添加后，每次请求可以自动携带需要的请求头。

5.1.配置全局请求头

package com.yuchenboot.admin.system.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;


@ComponentScan("com.test.controller") //扫描哪些包，需要生成在线文档
@EnableSwagger2
@EnableWebMvc
@Configuration
public class Swagger2Configuration {

    @Bean
    public Docket createDocket(){

        /*添加head头
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("x-access-token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());*/

        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .build()
                .apiInfo(this.apiInfo())
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());//将要添加的全局请求头放入构造器
                //.globalOperationParameters(pars)
    }



    public ApiInfo apiInfo(){
        //在线文档的编写人信息
        Contact contact=new Contact("rd","www.1024xh.com","123@qq.com");

        //在线文档的描述信息
        return new ApiInfoBuilder()
                .title("rd-admin")
                .description("API接口文档")
                .version("1.0.0")
                .contact(contact)
                .build();

    }

    /**
     * 添加全局请求头
     * @return
     */
    private List<ApiKey> securitySchemes() {
        List<ApiKey> apiKeys = new ArrayList<>();
        apiKeys.add(new ApiKey("x-access-token", "x-access-token", "header"));
        return apiKeys;
    }

    /**
     * 添加全局请求头
     * @return
     */
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex("^(?!auth).*$")).build());
        return securityContexts;
    }

    /**
     * 添加全局请求头
     * @return
     */
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("x-access-token", authorizationScopes));
        return securityReferences;
    }
}