Swagger学习(二)之SpringBoot集成Swagger2

我是一个小仓鼠01

已于 2022-07-23 22:44:56 修改

阅读量605

点赞数

分类专栏： Api对接文档文章标签： spring java mybatis

于 2022-07-23 18:40:09 首次发布

本文链接：https://blog.csdn.net/weixin_53998054/article/details/125948727

版权

Api对接文档专栏收录该内容

4 篇文章 1 订阅

订阅专栏

编写SpringBoot项目

编写SpringBoot项目，项目中controller中包含一个Handler，测试项目，保证程序可以正确使用

@RestController
@RequestMapping(value = "hello")
public class UserController {

 
}

仓库地址:https://mvnrepository.com/

导入相关依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- 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>

编写一个Hello工程

配置Swagger==>Config

@SpringBootApplication
@EnableSwagger2 //开启Swagger2
public class SwaggerDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerDemoApplication.class, args);
    }

}

配置Swagger信息


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
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
    
    //配置了Swagger 的  Docket的bean的实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact= new Contact("我是一只小仓鼠","https://blog.kuangstudy.com/","24736753@");
        return new ApiInfo(
                "练习的Swagger文档",
                "即使再小的帆也能远航",
                "1.0",
                "https://blog.kuangstudy.com/",
                contact,
                "Apache2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
    }
}

配置类


import com.google.common.base.Predicates;
import com.swagger.demo.anno.MyAnnotation4Swagger;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
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 //开启Swagger2
public class SwaggerConfig {
    //配置了Swagger 的  Docket的bean的实例
    @Bean
    public Docket docket(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()//获取Docket的选择器返回ApiSelectBuilder。构建选择器的。如:扫描什么包的注解。
                .apis(
                        Predicates.and(
                        Predicates.not//取反。false -> true true->false
                        (RequestHandlerSelectors.withMethodAnnotation(
                                //当方法上有注解的时候返回true
                                MyAnnotation4Swagger.class)//方法上的注解的时候返回true
                        ),
                                RequestHandlerSelectors.basePackage("com.swagger.demo")
                        )
                )
     
                .build();//重新构建Docket对象
    }

    //配置swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact= new Contact("我是一只小仓鼠","https://blog.kuangstudy.com/","24736753@");
        return new ApiInfo(
                "练习的Swagger文档",
                "即使再小的帆也能远航",
                "1.0",
                "https://blog.kuangstudy.com/",
                contact,
                "Apache2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
    }
}

配置扫描接口及开关

Docket.select

    //配置了Swagger 的  Docket的bean的实例
    //enable是否启动swagger,如果为False,则swagger
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors,配置扫描接口的方式
                //basePackage:指定要扫描的包
                //any():扫描全部
                //none():不扫描
                //withClassAnnotation:扫描类上的注解,参数是一个注解的反射对象
                //withMethodAnnotation:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.swagger.demo.controller"))
                //paths().过滤什么路径
                .paths(PathSelectors.ant("/kuang/**"))
                .build()
                ;
    }

使用正则表达式约束生成API文档的路径地址。

import com.google.common.base.Predicates;
import com.swagger.demo.anno.MyAnnotation4Swagger;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
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 //开启Swagger2
public class SwaggerConfig {
    //配置了Swagger 的  Docket的bean的实例
    @Bean
    public Docket docket(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()//获取Docket的选择器返回ApiSelectBuilder。构建选择器的。如:扫描什么包的注解。
                .apis(
                        Predicates.and(
                        Predicates.not//取反。false -> true true->false
                        (RequestHandlerSelectors.withMethodAnnotation(
                                //当方法上有注解的时候返回true
                                MyAnnotation4Swagger.class)//方法上的注解的时候返回true
                        ),
                                RequestHandlerSelectors.basePackage("com.swagger.demo")
                        )
                )
                .paths(
                        Predicates.or(//多个条件符合一个即可通过
                        PathSelectors.regex("/swagger/.*"),//使用正则表达式，约束生成API文档和路径地址
                        PathSelectors.regex("/swagger2/.*"),//使用正则表达式，约束生成API文档和路径地址
                        PathSelectors.regex("/.*")//使用正则表达式，约束生成API文档和路径地址

                        )
                )
                .build();//重新构建Docket对象
    }

    //配置swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact= new Contact("我是一只小仓鼠","https://blog.kuangstudy.com/","24736753@");
        return new ApiInfo(
                "练习的Swagger文档",
                "即使再小的帆也能远航",
                "1.0",
                "https://blog.kuangstudy.com/",
                contact,
                "Apache2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
    }
}

配置是否启动swagger


    //配置了Swagger 的  Docket的bean的实例
    //enable是否启动swagger,如果为False,则swagger
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)//enable是否启动Swagger,如果为false,则swagger不能在再浏览器中访问
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.demo.controller"))
                // .paths(PathSelectors.ant("/kuang/**"))
                .build()
                ;

我只希望我的swagger再生产环境使用发布的时候不使用？

1.判断是否是生产环境

2.注入enable()


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.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 //开启Swagger2
public class SwaggerConfig {

    //配置了Swagger 的  Docket的bean的实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的Swagger环境
        Profiles profiles= Profiles.of("dev","test");

        //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//enable是否启动Swagger,如果为false,则swagger不能在再浏览器中访问
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.demo.controller"))
                // .paths(PathSelectors.ant("/kuang/**"))
                .build()
                ;
    }

    //配置swagger信息=apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact= new Contact("我是一只小仓鼠","https://blog.kuangstudy.com/","24736753@");
        return new ApiInfo(
                "练习的Swagger文档",
                "即使再小的帆也能远航",
                "1.0",
                "https://blog.kuangstudy.com/",
                contact,
                "Apache2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
    }
}

启动类

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;


/**
*EnableSwagger2是springfox提供的一个注解，代表swagger2相关技术开启。
*会扫描当前类所在的包，以及包中所有的类型的注解。做swagger文档的定值
*
*
*
**/
@SpringBootApplication
/*@EnableSwagger2*/
@ComponentScan("com.swagger.demo.config")//
public class SwaggerDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerDemoApplication.class, args);
    }

}

分组和接口注释及小节

配置Api文档的分组

   .groupName("狂神")

如何配置多个分组；多个Docket实例即可

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

实体类


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

@ApiModel(value="用户实体类",description="描述实体使用的文字")
public class User {
    @ApiModelProperty(value="用户名",name="主键（id）",required=false,example="1",hidden=false)
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

Controller层

import com.swagger.demo.entity.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;

//operation接口
//@ApiOperation("Hello控制类")
@Api("Hello控制类")
@RestController
@RequestMapping(value = "hello")
public class UserController {

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

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

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


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

总结:

1.我们可以通过swagger给一些比较难理解的属性或者接口，增加注释信息

2.接口文档实时更新

3.可以在线测试

4.启动类的@ComponentScan("com.swagger.demo.config")注解

到demo层就行了不然controller层的扫描不能到

拓展：其他皮肤
我们可以导入不同的包实现不同的皮肤定义：
1、默认的访问 http://localhost:8080/swagger-ui.html

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

2、bootstrap-ui 访问 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

3、mg-ui 访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>