Swagger UI 2.0和3.0学习笔记

坚持学习永不言弃

已于 2023-02-22 12:32:19 修改

阅读量1.1k

点赞数 1

分类专栏： J2EE 文章标签： java

于 2022-08-03 11:46:26 首次发布

本文链接：https://blog.csdn.net/qq_41787812/article/details/126136848

版权

J2EE 专栏收录该内容

28 篇文章 0 订阅

订阅专栏

官网 https://swagger.io/

一、springboot集成Swagger 2.0+

1、导入依赖

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

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

2、配置Swagger 编写Config文件

2.1 配置接口扫描与作者信息

使用Dokcet对象中的 .select()方法

@Configuration  //表明这是一个配置类
@EnableSwagger2  //开启Swagger2
public class SwaggerConfig {

    @Value("${spring.swagger.enable}")
    private Boolean enableSwagger;

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("James") //API分组
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.it.es.web"))
                .paths(PathSelectors.ant("/hello/**"))  // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();//构建者模式
    }
    /**
     * 配置Swagger信息 apiinfo
     * @return
     */
   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
                   .title("单词计数服务") //设置文档的标题
                   .description("单词计数服务 API 接口文档") // 设置文档的描述
                   .version(VERSION) // 设置文档的版本信息-> 1.0.0 Version information
                   .termsOfServiceUrl("http://www.baidu.com") // 设置文档的License信息->1.3 License information
                   .build();

2.2 配置是否自动启动Swagger

在开发环境开启SwaggerUI ，生产环境关闭SwaggerUI 是因为开发环境是内部人员，生产环境是客户。为了程序的安全性需要关闭SwagggerUI

/**
     * 配置了Swagger 的Docket的bean实例,扫描接口的位置
     * .apis
     *   RequestHandlerSelectors 配置swagger扫描接口的方式
     *      basePackage() 指定要扫描哪些包
     *      any() 全部都扫描
     *      none() 全部不扫描
     *      withClassAnnotation() 扫描类上的注解 参数是一个注解的反射对象
     *      withMethodAnnotation() 扫描包上的注解
     * .paths
     *   PathSelectors 路径扫描接口
     *      ant 配置以xxx 开头的路径
     * @return
     */
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger 环境
        Profiles profiles =Profiles.of("dev","test");
        /**
         * 通过 environment.acceptsProfiles 返回的boolean值判断是否处在自己所设定的环境中
         */
        boolean flag = environment.acceptsProfiles(profiles);
        System.out.println(flag);
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("James")
                //.enable(flag) //enable配置是否自动启动swagger 如果为False则为不启动，浏览器中不能访问Swagger
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.study.swagger.controller"))
                //.paths(PathSelectors.ant("/hello/**"))
                .build();//构建者模式
    }

    /**
     * 配置Swagger信息 apiinfo
     * @return
     */
    private ApiInfo apiInfo(){

        //配置作者信息
        Contact DEFAULT_CONTACT = new Contact("James", "https://blog.csdn.net/zhanshixiang/", "zhanshixiang1997@163.com");
        return  new ApiInfo(
                "James 的Swagger API文档",
                "码出高效",
                "v1.0",
                "https://blog.csdn.net/zhanshixiang/",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

创建三个properties文件
application.properties
激活开发环境
在这里插入图片描述

2.3 配置API分组

/**
     * 开发A组的接口
     * @return
     */
    @Bean
    public Docket docketA(){
        return  new Docket(DocumentationType.SWAGGER_2)
                .groupName("A");
    }

    /**
     * 开发B组的接口
     * @return
     */
    @Bean
    public Docket docketB(){
        return  new Docket(DocumentationType.SWAGGER_2)
                .groupName("B");
    }

    /**
     * 开发C组的接口
     * @return
     */
    @Bean
    public Docket docketC(){
        return  new Docket(DocumentationType.SWAGGER_2)
                .groupName("C");
    }

在这里插入图片描述

2.4 配置实体类信息和接口方法

配置实体类信息

@ApiModel("用户实体类")
public class User implements Serializable {

    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

配置接口方法

@Api("Hello控制类")
@RestController
@RequestMapping("hello")
public class HelloController {


    @GetMapping(value = "say")
    public String hello() {
        return "hello ";
    }


    /**
     * 只要接口中,返回值中存在实体类，他就会被扫描到Swagger中
     * @return
     */
    @PostMapping(value = "/user")
    public User user(){
        return new User();
    }

    /**
     * ApiOperation接口，不是放在类上的，是方法
     * @return
     */
    @ApiOperation("hello控制类")
    @GetMapping(value = "/hello2")
    public String hello2(@ApiParam("用户名") String username){
        return "hello"+username;
    }

    @ApiOperation("Post测试类")
    @PostMapping(value = "/post")
    public User post(@ApiParam("用户") User user){
        return user;
    }
    
}

二、 SpringBoot整合Swagger3.0+

官方文档 http://springfox.github.io/springfox/docs/current/

简介

Swagger3在Swagger2的基础上进行了部分升级，与swagger2相比新版的swagger3配置更少，使用更加方便。
    一个重要的优化是依赖的引入，由之前的多个依赖变更为一个依赖，跟随springboot-starter风格，同时引入了新的开关注解@EnableOpenApi 以代替@EnableSwagger2 。
因此，集成工作变得更加的简便了，必要工作只有两个，添加swagger3的starter依赖包，在springboot主程序类添加@EnableOpenApi开关注解。

1、快速入门

1.1 引入依赖

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

2.2 启动类添加开关注解@EnableOpenApi

作用：表示开启生成接口文档功能，只有开启了OpenApi，才能实现生成接口文档的功能

@EnableOpenApi
@SpringBootApplication
public class SwaggerApplication {
 
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
 
}

2.3 配置Swagger配置文件

// 表明当前类是配置类
@Configuration
public class SwaggerConfig {
 
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()// 为api选择启动生成器
             	//RequestHandlerSelectors,配置要扫描接口的方式
                //basePackage:指定要扫描的包
                //any()：扫描全部
                //none():不扫描
                //.withClassAnnotation():扫描类上的注解
                //.withMethodAnnotation():扫描方法上的注解
             .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 指定要生成api文档的根包       
                .paths(PathSelectors.any())// 路径配置
                .build();
    }
 
    /**
     * 创建一个ApiInfo对象
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title("SpringBoot整合Swagger3")
                // 简介
                .description("更多请咨询服务开发者小龍")
                // 作者信息：作者姓名、作者地址、作者邮箱
                .contact(new Contact("小龍", "https://blog.csdn.net/wangzhilong1996", "123456@qq.com"))
                // 版本号
                .version("1.0")
                .build();
    }
}

2.4 配置实体类信息和接口方法

和swagger 2.X一样

2.5 引入第三方UI包

原生的ui页面并不美观，我们可以选择使用第三方的ui包来美化页面，当然，市面上的第三方ui包有很多，大家可以找一个自己喜欢的，不一定用我的。

<!-- swagger 第三方ui包 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

2.6 访问地址

swagger3跟swagger2访问地址有所区别：swagger3的地址是 http://localhost:8080/swagger-ui/

2.7 如果报错404

package com.jdwifi.g1335333249.config;
 
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
@EnableWebMvc
@Configuration
public class WebConfig extends WebMvcConfigurationSupport {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations(
                "classpath:/static/");
        registry.addResourceHandler("swagger-ui.index.html").addResourceLocations(
                "classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations(
                "classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }
}

2.8 从现有 2.x 版本迁移 3.X版本

上述说明其实在swagger官网有说，但是大部分人不看而已，所以给出链接：如何从swagger老版本迁移到3.0.0

Spring Boot 应用程序

注意：希望得到反馈以使其更好

删除显式依赖 springfox-swagger2
删除@EnableSwagger2注释
添加springfox-boot-starter依赖
Springfox 3.x 移除了对 guava 和其他 3rd 方库的依赖（还不是零依赖！依赖于 spring 插件和用于注释和模型的开放 api 库）所以如果你使用了 guava 谓词/函数，这些将需要转换到 java 8 函数接口
如果您正在使用 WebMvc 但您还没有使用该@EnableWebMvc注解，请添加此注解。

拓展
1、@EnableOpenApi注解到底是什么作用，尝试不加该注解，仍谈可以正常生成文档

2、如何在项目中实现不将swagger应用到生产环境中去