自学springboot之整合swagger

最新推荐文章于 2025-06-16 16:13:01 发布

原创最新推荐文章于 2025-06-16 16:13:01 发布 · 1.5k 阅读

CC 4.0 BY-SA版权

本文介绍了如何在SpringBoot项目中集成Swagger，用于创建和管理API文档。内容涵盖Swagger的作用、前后端分离的优势、Swagger的基本使用，包括配置、实体类和Controller的注解使用，以及Swagger的主要优点和安全注意事项。适合于想提升API文档管理和测试效率的开发者。

springboot + Swagger

学习目标：

了解Swagger的作用和概念
了解前后端分离
在SpringBoot中集成Swagger

swagger简介

现在开发，很多采用前后端分离的模式，前端只负责调用接口，进行渲染，前端和后端的唯一联系，变成了API接口。因此，API文档变得越来越重要。swagger是一个方便我们更好的编写API文档的框架，而且swagger可以模拟http请求调用。

大部分采取的方式：Vue + SpringBoot，Vue通过js渲染页面，后端把数据传递给js，早期前端只负责写页面，然后把写好的HTML页面给后端，后端使用模板引擎（Jsp，Thymeleaf、 freemarker）进行开发。

前后端分离的好处：各自开发，相对独立，松耦合，前后端通过API进行交互，后端提供接口给前端，前端去调用该接口，但可能会导致前后端团队人员不能做到及时协商，出现一些问题。解决方式：早期使用实时更新文档，但非常繁琐，后来又使用postman来进行一些测试。

使用：

新建一个springboot+web项目

导入依赖

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.3.0.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.ryan</groupId>
    <artifactId>springboot-08-swagger</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot-08-swagger</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>11</java.version>
    </properties>

    <dependencies>
        <!--springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!--springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
            <exclusions>
                <exclusion>
                    <groupId>org.junit.vintage</groupId>
                    <artifactId>junit-vintage-engine</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

测试环境：略

编写Swagger配置类

package com.ryan.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import springfox.documentation.RequestHandler;
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;

import java.util.ArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //swagger有自己的bean实例——Docket
    //配置了swagger
    @Bean
    public Docket docket(){
        //假设这里有一个业务，我只希望在生产环境中使用swagger，其他环境不需要
        //第一步，配置多个环境，第二步：传一个环境参数（Environment），
        //第三步：获取当前环境（environment.acceptsProfiles(profiles)），第四步：判断环境，第五步，传到enable方法中即可
        //这里就不多测试了
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //自定义组名（团队开发中的一组），如果有多个组，就是多个Docket，一个组对应一个Docket
                .groupName("ryan")
                .enable(true)//是否开启swagger，如果为false，则swagger不能在浏览器中被访问
                //测试题，
                .select()
                //配置指定需要扫描的包，除了basePackage还有其他的可以点出来看，例如any none...
                .apis(RequestHandlerSelectors.basePackage("com.ryan.swagger.controller"))
                //.paths(PathSelectors.any())//此方法为过滤方法
                .build();
    }

    public ApiInfo apiInfo(){

        Contact contact = new Contact("ryan", "https://blog.youkuaiyun.com/codebeef", "635726567@qq.com");

        return new ApiInfo(
                "ryan的SwaggerApi文档",
                "努力努力再努力",
                "v1.0",
                "https://blog.youkuaiyun.com/codebeef",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

效果：
在这里插入图片描述
编写实体类

package com.ryan.swagger.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

    public User() {
    }

    public User(String username, String password) {
        this.username = username;
        this.password = password;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

效果：通过注解给实体类添加api
在这里插入图片描述
编写controller

package com.ryan.swagger.controller;

import com.ryan.swagger.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(description = "用户管理API")
@RestController
public class HelloController {

    @ApiOperation("添加用户")
    @PostMapping("/add")
    public User add(@ApiParam("用户名") String username, @ApiParam("密码") String password){
        return new User();
    }

    @ApiOperation("修改用户")
    @PostMapping("/update")
    public String update(@ApiParam("用户名") String username, @ApiParam("密码") String password){
        return "修改完成";
    }

    @ApiOperation("删除用户")
    @GetMapping("/delete")
    public String delete(@ApiParam("用户编号") Integer id){
        return "已删除";
    }

    @ApiOperation("查询用户")
    @RequestMapping("/query")
    public User query(){
        User user = new User();
        user.setUsername("ryan");
        user.setPassword("ryan123");
        return new User();
    }
}

效果：通过注解添加api，注意RequestMapping会把所有方式都显示出来
在这里插入图片描述
还可以在上面进行测试

注解总结：

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

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiModel：用对象来接收参数，修饰类

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述，一般描述错误的响应

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiParam：单个参数描述

@ApiImplicitParam：一个请求参数，用在方法上

@ApiImplicitParams：多个请求参数

总要的两个依赖

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