【Spring Boot】018-Swagger

訾博ZiBo

发布于 2025-01-06 15:39:04

3500

代码可运行

文章被收录于专栏：全栈开发工程师全栈开发工程师

运行总次数：0

代码可运行

最新更新：2020年9月22日08:09:35

一、概述

1、简介

前后端分离：

vue + spring boot；

后端时代：

前端只管理静态页面；

html==>后端，模板引擎 JSP==>后端是主力；

前后端分离时代：

后端：后端控制层、服务层、持久层【后端团队】；

前端：前端控制层、视图层【前端团队】；

前端伪造后端数据——json，在写前端页面的时候已经存在，不需要后端，前端工程依旧能够跑起来；

前后端如何交互：===>API；

前后端分离的好处：相对独立，松耦合，前后端可以部署在不同的服务器上；

产生一个问题：

前后端集成联调，前后端人员无法做到及时协商、尽早解决，最终导致问题集中爆发；

解决方案：

首先指定schema【计划】实时更新最新的API，降低集成风险；

早些年：制定word计划文档；

前后端分离：

前端测试后端接口：postman；

后端提供接口需要实时更新最新的消息及改动！

2、Swagger

简介：

号称世界上最流行的API框架；

RestFul API文档自动生成工具==>API文档与API定义同步更新；

直接运行，在线测试API接口；

支持多种语言：Java、PHP等等；

官网：

https://swagger.io/

在项目中实际用Swagger：

swagger2、ui；

二、Spring Boot集成Swagger

1、新建Spring Boot项目，勾选Web模块，并导入坐标

swagger2：

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

swagger-ui：

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

2、写一个HelloController

package com.zibo.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }

}

3、运行测试

4、配置Swagger（写Config）

package com.zibo.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration //等价于@Component
@EnableSwagger2 //开启Swagger
public class SwaggerConfig {

}

5、运行测试

（当版本为3.0.0无法访问swagger-ui.html，所以改成了2.9.2）

三、配置Swagger基本信息

1、Swagger的bean实例Docket

package com.zibo.config;

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 //等价于@Component
@EnableSwagger2 //开启Swagger
public class SwaggerConfig {
    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(@Qualifier("apiInfo")ApiInfo apiInfo){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo);
    }
    //配置Swagger信息apiInfo
    @Bean
    public ApiInfo apiInfo(){
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }

}

2、运行测试

四、配置扫描接口

1、配置扫描接口

package com.zibo.config;

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 //等价于@Component
@EnableSwagger2 //开启Swagger
public class SwaggerConfig {
    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(@Qualifier("apiInfo")ApiInfo apiInfo){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                //RequestHandlerSelectors配置扫描接口的方式
                //basePackage：指定扫描的包（常用）
                //any：扫描全部
                //none：都不扫描
                //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation：扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.zibo.controller"))
                //paths过滤路径
                //.paths(PathSelectors.ant("/zibo/**"))
                .build();
    }
    //配置Swagger信息apiInfo
    @Bean
    public ApiInfo apiInfo(){
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }

}

2、运行测试

五、配置是否启动Swagger

（默认为true）

1、代码里设置（一行代码）

package com.zibo.config;

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 //等价于@Component
@EnableSwagger2 //开启Swagger
public class SwaggerConfig {
    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(@Qualifier("apiInfo")ApiInfo apiInfo){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                //★★★配置是否开启Swagger
                .enable(false)
                .select()
                //RequestHandlerSelectors配置扫描接口的方式
                //basePackage：指定扫描的包（常用）
                //any：扫描全部
                //none：都不扫描
                //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation：扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.zibo.controller"))
                //paths过滤路径
                //.paths(PathSelectors.ant("/zibo/**"))
                .build();
    }
    //配置Swagger信息apiInfo
    @Bean
    public ApiInfo apiInfo(){
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }

}

2、运行测试

3、如果是开发环境则启动Swagger

第一步：添加两个配置文件，分别是开发环境和发布环境

application.properties：

spring.profiles.active=pro

application.properties-dev：

server.port=8081

application.properties-pro：

server.port=8081

第二步：在SwaggerConfig类中获取当前环境

package com.zibo.config;

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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 //等价于@Component
@EnableSwagger2 //开启Swagger
public class SwaggerConfig {
    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(@Qualifier("apiInfo")ApiInfo apiInfo, Environment environment){
        //设置要显示的Swagger环境
        Profiles dev = Profiles.of("dev");
        //如果当前是dev环境，则返回true
        boolean flag = environment.acceptsProfiles(dev);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                //配置是否开启Swagger
                .enable(flag)
                .select()
                //RequestHandlerSelectors配置扫描接口的方式
                //basePackage：指定扫描的包（常用）
                //any：扫描全部
                //none：都不扫描
                //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation：扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.zibo.controller"))
                //paths过滤路径
                //.paths(PathSelectors.ant("/zibo/**"))
                .build();
    }
    //配置Swagger信息apiInfo
    @Bean
    public ApiInfo apiInfo(){
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }

}

第三步：运行测试

第四步：修改为测试环境

spring.profiles.active=dev

第五步：运行测试

六、配置API文档的分组与注释

1、设置组名

设置分组名字.groupName("名字")：

package com.zibo.config;

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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 //等价于@Component
@EnableSwagger2 //开启Swagger
public class SwaggerConfig {
    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(@Qualifier("apiInfo")ApiInfo apiInfo, Environment environment){
        //设置要显示的Swagger环境
        Profiles dev = Profiles.of("dev");
        //如果当前是dev环境，则返回true
        boolean flag = environment.acceptsProfiles(dev);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                //配置是否开启Swagger
                .enable(flag)
                //这是文档分组
                .groupName("訾博")
                .select()
                //RequestHandlerSelectors配置扫描接口的方式
                //basePackage：指定扫描的包（常用）
                //any：扫描全部
                //none：都不扫描
                //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation：扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.zibo.controller"))
                //paths过滤路径
                //.paths(PathSelectors.ant("/zibo/**"))
                .build();
    }
    //配置Swagger信息apiInfo
    @Bean
    public ApiInfo apiInfo(){
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }

}

运行测试：

2、设置多个分组

（写多个Docket即可）

代码：

package com.zibo.config;

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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 //等价于@Component
@EnableSwagger2 //开启Swagger
public class SwaggerConfig {
    @Bean
    public Docket docketA(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }

    @Bean
    public Docket docketB(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }

    @Bean
    public Docket docketC(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(@Qualifier("apiInfo")ApiInfo apiInfo, Environment environment){
        //设置要显示的Swagger环境
        Profiles dev = Profiles.of("dev");
        //如果当前是dev环境，则返回true
        boolean flag = environment.acceptsProfiles(dev);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                //配置是否开启Swagger
                .enable(flag)
                //这是文档分组
                .groupName("訾博")
                .select()
                //RequestHandlerSelectors配置扫描接口的方式
                //basePackage：指定扫描的包（常用）
                //any：扫描全部
                //none：都不扫描
                //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation：扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.zibo.controller"))
                //paths过滤路径
                //.paths(PathSelectors.ant("/zibo/**"))
                .build();
    }
    //配置Swagger信息apiInfo
    @Bean
    public ApiInfo apiInfo(){
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本
                "http://terms.service.url/组织链接", // 组织链接
                contact, // 联系人信息
                "Apach 2.0 许可", // 许可
                "许可链接", // 许可连接
                new ArrayList<>()// 扩展
        );
    }

}

测试结果：

3、实体类配置

实体类User：

package com.zibo.pojo;

public class User {
    public String username;
    public String password;
}

在HelloController中添加方法：

package com.zibo.controller;

import com.zibo.pojo.User;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }

    //返回值存在实体类，就会被Swagger扫描到
    @RequestMapping("/user")
    public User user(){
        return new User();
    }


}

测试结果：

4、给实体类加注释

代码：

package com.zibo.pojo;

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

//@Api("注释内容")
@ApiModel("用户实体类") //给实体类加注释
public class User {
    //属性要用public修饰
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

测试结果：

5、给方法和参数加注释

代码：

package com.zibo.controller;

import com.zibo.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @ApiOperation("Hello方法")//只能放在方法上
    @RequestMapping("/hello")
    public String hello(@ApiParam("用户名") String username){
        return "hello" + username;
    }

    //返回值存在实体类，就会被Swagger扫描到
    @RequestMapping("/user")
    public User user(){
        return new User();
    }


}

运行结果：

七、关于Swagger测试功能的说明

八、总结

1、可以添加注释信息；

2、接口文档实时更新；

3、可以在线测试；

九、源代码

链接：https://pan.baidu.com/s/111Lzv9mJ6_Hkb8pGpnIr3A 提取码：zibo

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2025-01-06，如有侵权请联系 cloudcommunity@tencent.com 删除

boot

本文分享自作者个人站点/博客前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度