springboot整合swagger

1)简介:

作为后端开放人员,最烦的事就是自己写接口文档和别人没有写接口文档,不管是前端还是后端开发,多多少少都会被接口文档所折磨,前端会抱怨后端没有及时更新接口文档,而后端又会觉得编写接口文档太过麻烦。

Swagger 可以较好的解决接口文档的交互问题,以一套标准的规范定义接口以及相关的信息,就能做到生成各种格式的接口文档,生成多种语言和客户端和服务端的代码,以及在线接口调试页面等等。只需要更新 Swagger 描述文件,就能自动生成接口文档,做到前端、后端联调接口文档的及时性和便利性。

Swagger是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

2)优势:

  • 支持 API 自动生成同步的在线文档:使用 Swagger 后可以直接通过代码生成文档,不再需要自己手动编写接口文档了,对程序员来说非常方便,可以节约写文档的时间去学习新技术。

  • 提供 Web 页面在线测试 API:光有文档还不够,Swagger 生成的文档还支持在线测试。参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口。

3)SpringBoot整合Swagger

1.pom.xml的properties便签中加入以下代码

   <properties>
        <swagger.versiion>3.0.0</swagger.versiion>
    </properties>

2.在pom.xml的dependencies标签中添加Swagger依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>${swagger.versiion}</version>
        </dependency>

 3.创建config包,在config包下添加Swagger配置类

package com.cqh.config;

import io.swagger.annotations.ApiOperation;
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.oas.annotations.EnableOpenApi;
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;

@Configuration
//@EnableSwagger2
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 为api选择启动生成器
                .select()
                // 指定要生成api文档的根包
                .apis(RequestHandlerSelectors.basePackage("com.cqh.controller"))  //添加ApiOperiation注解的被扫描
                .paths(PathSelectors.any())
                .build();
 
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title("项目测试")
                // 简介
                .description("测试练习")
                // 作者信息:作者姓名、作者地址、作者邮箱
                .contact(new Contact("cqh","https://www.cqh.com","666666.@qq.com"))
                .version("1.0").build();
    }
 
}

浏览器访问http://localhost:8080/swagger-ui/#/ 

如果出现

pom.xml中 加上

         <dependency>
            <groupId>org.springframework.plugin</groupId>
            <artifactId>spring-plugin-core</artifactId>
            <version>2.0.0.RELEASE</version>
        </dependency>

4)添加文档内容

在完成了上述配置后,其实已经可以生产文档内容,但是这样的文档主要针对请求本身,描述的主要来源是函数的命名,通常需要自己增加一些说明来丰富文档内容。

Swagger使用的注解及其说明:

@Api:用在类上,说明该类的作用。

@ApiOperation:注解来给API增加方法说明。

@ApiParam:定义在参数上

@ApiResponses:用于表示一组响应

@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息 l code:数字,例如400 l message:信息,例如"请求参数没填好" l response:抛出异常的类

@ApiModel:描述一个Model的信息

l @ApiModelProperty:描述一个model的属性

案例

1.数据库导入

# Host: localhost  (Version 5.7.23-log)
# Date: 2023-12-05 13:26:01
# Generator: MySQL-Front 6.0  (Build 2.20)


#
# Structure for table "account_info"
#

CREATE TABLE `account_info` (
  `account` varchar(11) NOT NULL COMMENT '用户账号,主键',
  `acc_name` varchar(50) NOT NULL COMMENT '用户姓名',
  `password` varchar(255) NOT NULL COMMENT '鐢ㄦ埛瀵嗙爜锛岄粯璁ゆ墜鏈哄彿鍚?浣?',
  `acc_phone` varchar(11) NOT NULL COMMENT '手机号11位,唯一',
  `is_enable` tinyint(1) NOT NULL COMMENT '是否启用(1:启用,0:未启用)',
  `create_time` datetime NOT NULL COMMENT '创建时间',
  `update_time` datetime NOT NULL COMMENT '更新时间',
  PRIMARY KEY (`account`),
  UNIQUE KEY `uk_phone` (`acc_phone`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

#
# Data for table "account_info"
#

INSERT INTO `account_info` VALUES ('YZ0001','admin','92159b1631dae48aa523875174e3ea60','13811345670',1,'2023-08-18 11:34:28','2023-08-18 11:34:28'),('YZ0002','admin','986fa807bbe0c721702868bae6ef8a33','13811345679',1,'2023-08-18 11:34:38','2023-08-18 11:34:38'),('YZ0003','admin2','7d839f278639a38b2ba83ad67ab836a2','13811345677',1,'2023-08-18 14:46:05','2023-08-18 14:46:05'),('YZ0004','admin2','35ea60fd301a3895245aff0ca4947d9e','13811345674',1,'2023-08-18 15:03:12','2023-08-18 15:03:12');
2.pom.xml配置依赖导入

<?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.1.4.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <groupId>com.cqh</groupId>
    <artifactId>springboot1129</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot1129</name>
    <description>springboot1129</description>
    <properties>
        <java.version>8</java.version>
        <swagger.versiion>3.0.0</swagger.versiion>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
        </dependency>
        <dependency>
            <groupId>org.mybatis.spring.boot</groupId>
            <artifactId>mybatis-spring-boot-starter</artifactId>
            <version>2.1.0</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>${swagger.versiion}</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.plugin</groupId>
            <artifactId>spring-plugin-core</artifactId>
            <version>2.0.0.RELEASE</version>
        </dependency>

    </dependencies>

    <build>

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


       
    </build>

</project>
3.数据库连接配置


spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://127.0.0.1:3306/ssmlmh?serverTimezone=Asia/Shanghai&characterEncoding=utf-8
    username: root
    password: root



mybatis:
  mapper-locations: classpath*:mapper/*.xml
  type-aliases-package: com.cqh.entity


4.创建实体类

package com.cqh.entity;

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

@Data
@ApiModel(
        value = "AccountInfoVo",
        description = "人员账号信息"
)
public class AccountInfo {

    @ApiModelProperty(value = "登录账号")
    private String account;
    @ApiModelProperty(value = "人员名称")
    private String accName;
    @ApiModelProperty(value = "登陆密码")
    private String password;

    public String getAccount() {

        return account;
    }

    public void setAccount(String account) {
        this.account = account;
    }

    public String getAccName() {
        return accName;
    }

    public void setAccName(String accName) {
        this.accName = accName;
    }

    public String getPassword() {
        return password;
    }

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

    @Override
    public String toString() {
        return "AccountInfo{" +
                "account='" + account + '\'' +
                ", accName='" + accName + '\'' +
                ", password='" + password + '\'' +
                '}';
    }
}
5. swagger配置类也不能忘记

package com.cqh.config;

import io.swagger.annotations.ApiOperation;
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.oas.annotations.EnableOpenApi;
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;

@Configuration
//@EnableSwagger2
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 为api选择启动生成器
                .select()
                // 指定要生成api文档的根包
                .apis(RequestHandlerSelectors.basePackage("com.cqh.controller"))  //添加ApiOperiation注解的被扫描
                .paths(PathSelectors.any())
                .build();
 
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title("项目测试")
                // 简介
                .description("测试练习")
                // 作者信息:作者姓名、作者地址、作者邮箱
                .contact(new Contact("cqh","https://www.cqh.com","666666.@qq.com"))
                .version("1.0").build();
    }
 
}

6.mapper配置文件

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd" >
<mapper namespace="com.cqh.mapper.AccountInfoMapper">


    <select id="selectAll" parameterType="String" resultType="com.cqh.entity.AccountInfo">
        SELECT account,acc_Name AS accName,password FROM account_info
    </select>

<select id="selectByName" parameterType="String" resultType="com.cqh.entity.AccountInfo">
    SELECT account, acc_Name AS accName, password
    FROM account_info
    WHERE acc_name LIKE CONCAT('%', #{accName}, '%');</select>
</mapper>

7.mapper接口

package com.cqh.mapper;

import com.cqh.entity.AccountInfo;

import java.util.List;

public interface AccountInfoMapper {

    List<AccountInfo> selectAll();

    List<AccountInfo> selectByName(String accName);
}

 8.service层接口

package com.cqh.service;

import com.cqh.entity.AccountInfo;

import java.util.List;

public interface AccountService {
    List<AccountInfo> selectAll();
//改一下返回类型
    List<AccountInfo> selectByName(String accName);
}

9.service实现类 

package com.cqh.service.impl;

import com.cqh.entity.AccountInfo;
import com.cqh.mapper.AccountInfoMapper;
import com.cqh.service.AccountService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class AccountServiceImpl implements AccountService {

    @Autowired
    private AccountInfoMapper accountInfoMapper;
    @Override
    public List<AccountInfo> selectAll() {
        return accountInfoMapper.selectAll();
    }

    @Override
    public List<AccountInfo> selectByName(String accName) {
        return accountInfoMapper.selectByName(accName);
    }
}
 10.控制器层

package com.cqh.controller;

import com.cqh.entity.AccountInfo;
import com.cqh.service.AccountService;

import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(value = "积分等级管理",tags = {"人员信息"})
public class AccountInfoController {

    @Autowired
    private AccountService accountService;

    @GetMapping("/getByName/{accName}")
    @ApiOperation("根据账号查询人员信息")
    public List<AccountInfo> getById(@ApiParam(value = "要查询的账号",required = true,example = "1") @PathVariable String accName){

        return accountService.selectByName(accName);
    }
}
 11.浏览器访问

http://localhost:8080/swagger-ui/#/

12.找到要测试的接口

13.点击ty it out 

14.输入要查询的类容
 15.点击执行

16.查看执行结果

Swagger2美化页面

添加依赖

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

启动项目,访问http://localhost:8080/doc.html

 

<think>好的,我现在需要帮助用户了解如何在Spring Boot项目中集成Swagger来生成API文档。根据用户提供的引用内容,我需要整理出一个清晰的步骤指南,同时确保遵循系统级指令,比如正确使用LaTeX格式和生成相关问题。 首先,我需要回顾用户提供的引用内容。引用[1]介绍了Spring BootSwagger的基本概念,以及整合的必要性。引用[3]提到了准备工作,比如JDK版本、IDE、构建工具和所需依赖。引用[5]提到了依赖版本的问题,特别是Spring BootSwagger版本的兼容性。引用[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
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

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

余额充值