【SpringBoot集成Swagger】

刘星雨855

已于 2022-12-14 08:55:10 修改

阅读量796

点赞数

于 2022-12-14 08:54:28 首次发布

本文链接：https://blog.youkuaiyun.com/lzy99534/article/details/128298413

版权

本文介绍了如何在SpringBoot项目中集成Swagger，包括引入依赖、配置文件设置、创建配置类和使用Swagger注解来详细说明接口。通过@Api、@ApiOperation等注解，可以自动生成接口文档，便于接口管理和测试。

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

swagger访问地址：http://localhost:{server-port}/swagger-ui.html

1、引入依赖

 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

2、添加配置文件

   # 开启swagger 
   swagger.enable=true

3、创建配置类

package com.task.test.config;

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;

@Configuration
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore注解的API）
                .apis(RequestHandlerSelectors.basePackage("com.task.test.controller"))
                // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                // 页面标题
                .title("billing api")
                // 描述
                .description("自定义系统API接口服务文档")
                .build();
    }
}

4、使用

4.1、实体类

@Data
@ApiModel("用户实体类")
public class Student implements Serializable {
    private static final long serialVersionUID = -5663443621333915042L;

    @ApiModelProperty("学生id")
    private Long id;
    @ApiModelProperty("学生姓名")
    private String name;
    @ApiModelProperty("学生所在班级")
    private Integer classId;
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date createTime;
    @ApiModelProperty("班级信息")
    private BanJi banJi;
}

4.2、controller类

package com.task.test.controller;


import com.task.test.entity.Student;
import com.task.test.service.StudentService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 * @Date 2022/11/28
 * @Author liuziyan
 * @description
 */
@Slf4j
@RestController
@RequestMapping("/crud")
@Api(value = "CrudController", tags = "学生管理模块")
public class CrudController {

    @Autowired
    private StudentService studentService;

    @ApiOperation("查询学生接口")
    @GetMapping("/list")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "学生ID",readOnly = true,dataType = "Integer"),
            @ApiImplicitParam(name = "name",value = "学生姓名",readOnly = true,dataType = "String"),
            @ApiImplicitParam(name = "classId",value = "学生所在班级ID",readOnly = true,dataType = "Integer"),
            @ApiImplicitParam(name = "createTime",value = "入学时间",readOnly = true,dataType = "Date")
    })
    public List<Student> list(Student student){
        List<Student> list = studentService.list(student);
        return list;
    }

    
}

4.3、效果

5、swagger注解

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

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数
转载：什么是swagger以及swagger注解详解_mischen520的博客-优快云博客_swgger 请求类型什么意思