swagger2.9.2教程 与swagger3.0.0教程

程序员的日常:

程序员某天的对话

阿媴 阿猿 阿袁 你好！阿猿, 最近在干嘛? 还能干嘛，不是在code就是想方设法学习code？ 就这? 学习是件很简单的事情呀 打量着阿袁...似乎有什么话对他说... 你是哪一个(guo),你们认识吗? 阿媴 阿猿 阿袁

学习是一辈子的事情,不是吗?

这部分没有别的内容,只看行动!

swagger的使用

springboot整合swagger

程序员那点事就是实践实践再实践

1. 准备一个经典的工程

2. 导入swagger相关包

swagger的相关包

如果是使用swagger_2版本那么就用下面的swagger版本就可以,

注意:这里要使用springboot的2.5及以下版本, ----但是这涉及到漏洞的问题,所以最好还是使用2.7.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>

swagger_2 版本的相关的依赖明细

使用springboot2.5运行

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

3. 配置swagger

@Configuration
@EnableSwagger2//开启swagger的注解
public class SwaggerConfig {
}

4. 运行工程

访问Url---->>http://localhost:8888/swagger-ui.html

swagger界面功能介绍–>>

访问时的文件存放位置—>>(swagger-ui 2.9.2 与3.0.0访问地址发生了一些变化

在这里我们在配置文件中实际上什么配置也没有写,我们来看一下,如何配置swagger

我们手动配置一下

@EnableSwagger2
@Configuration
public class Swagger2Config {


    Contact contact = new Contact("Gavin", "https://varyu-program.gitee.io/road2-coding/", "[e-mail]");

    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(createApiInfo());
    }


    @Bean
    public ApiInfo createApiInfo() {

        return new ApiInfo("swagger2的使用",
                "学习使我快乐",
                "版本1.0",
                "localhost:8888/test",
                contact, "GPL",
                "http://wwww.baidu.com",
                new ArrayList<>());
    }

这里切换到swagger 3.0版本

如果是使用swagger3.0版本那么可以使用spring提供的swagger3的启动包,方便快捷,同时也可以配合使用最新版本的springboot版本,我想着反正最后都要升级成swagger 3.0.0,不如就直接肝swagger3.0.0,

反正变动不大,

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

引入一个启动依赖即可–springfox-boot-starter

然后启动工程---->>http://localhost:8888/swagger-ui/index.html

在controller层,我们可以看到各种请求方式,在测试的时候也很方便

5. 可选接口展示----过滤

默认是把所有接口都扫描了,但是我们有时只需要提供部分接口即可—>>

@Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                //api文档信息
                .apiInfo(createApiInfo())
                //配置可选扫描接口
                .select()
                //RequestHandlerSelectors配置要扫描接口的方式
                //any  扫描全部
                //withClassAnnotation 扫描类上注解
                //withMethodAnnotation 扫描方法上注解
                .apis(RequestHandlerSelectors.basePackage("com.gavin.controller")).build();
    }

6. 关闭swagger扫描

@Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                //api文档信息
                .apiInfo(createApiInfo())
                //关闭swagger扫描
                .enable(false)
                 .build();
    }

swagger在开发环境/测试环境启用,在生产环境不启用

首先我们在发布时一般不会将swagger相关代码移除,而是选择通过enable(false)的方式进行关闭swagger,

所以解决思路是
1,判断是否是生产环境----
2,关闭swagger

代码如下—

@Bean
    public Docket createRestApi(Environment environment) {
        //获取配置文件中的属性值
        String environmentProperty = environment.getProperty("spring.profiles.active");
        if (environmentProperty.equals("dev")){
            return new Docket(DocumentationType.SWAGGER_2)
                    //api文档信息
                    .apiInfo(createApiInfo())
                    //关闭swagger扫描
                    .enable(false)
                    ;
        }
//        Profiles profiles= Profiles.
        return new Docket(DocumentationType.SWAGGER_2)
                //api文档信息
                .apiInfo(createApiInfo())
                //关闭swagger扫描
                .enable(true);
    }

传入一个–Environment (接口)对象,该接口下提供了四种方法,有一个已经被废弃了,

package org.springframework.core.env;

public interface Environment extends PropertyResolver {
    String[] getActiveProfiles();

    String[] getDefaultProfiles();

    /** @deprecated */
    @Deprecated
    boolean acceptsProfiles(String... profiles);

    boolean acceptsProfiles(Profiles profiles);
}

getActiveProfiles与getDefaultProfiles底层是一样的

acceptsProfiles要传入Profiles(接口)对象,里面由static 方法

整体的演示代码–>>

@Bean
    public Docket createRestApi(Environment environment) {
        //获取配置文件中的属性值
        String environmentProperty = environment.getProperty("spring.profiles.active");

        //直接判断你是否是生产环境
        boolean flag = environment.acceptsProfiles(Profiles.of("pro"));
        System.out.println(false);
        if(flag){
            return new Docket(DocumentationType.SWAGGER_2)
                    //api文档信息
                    .apiInfo(createApiInfo())
                    //关闭swagger扫描
                    .enable(false)
                    ;
        }
       if (environmentProperty.equals("dev")){
            return new Docket(DocumentationType.SWAGGER_2)
                    //api文档信息
                    .apiInfo(createApiInfo())
                    //关闭swagger扫描
                    .enable(false)
                    ;
        }
 
        return new Docket(DocumentationType.SWAGGER_2)
                //api文档信息
                .apiInfo(createApiInfo())
                //关闭swagger扫描
                .enable(true);
    }

1. 设置多个分组

设置多个Docket即可

我们可以配置一些不同的粗略来满足不同的需求

8. 设置实体类

@ApiModel(description = "部门类")
public class Dept implements Serializable {
    @ApiModelProperty("部门编号")
    private Integer deptno;
    @ApiModelProperty("部门名称")
    private String dname;
    @ApiModelProperty("部门位置")
    private String loc;

    private static final long serialVersionUID = 1L;

    public Integer getDeptno() {
        return deptno;
    }

    public void setDeptno(Integer deptno) {
        this.deptno = deptno;
    }

    public String getDname() {
        return dname;
    }

    public void setDname(String dname) {
        this.dname = dname;
    }

    public String getLoc() {
        return loc;
    }

    public void setLoc(String loc) {
        this.loc = loc;
    }
}

在model层—>>卡一看到变化----加了备注

swagger一些常用注解

一些常用注解说明

     @Api：用在controller类，描述API接口
     @ApiOperation：描述接口方法
     @ApiModel：描述对象
     @ApiModelProperty：描述对象属性
     @ApiImplicitParams：描述接口参数
     @ApiResponses：描述接口响应
     @ApiIgnore：忽略接口方法

@ApiImplicitParams：描述接口参数 的使用

@EnableOpenApi
@Api(description = "部门API")
@RestController("/dept")
public class KmailController {
    @Resource
    private DeptService deptService;

    @ApiOperation("/查询职位存在")
    @RequestMapping("/test")
    public String getDname() {
        String sales = deptService.queryDbname("SALES");
        return sales;
    }

    @ApiOperation("查询部门")
    @ApiImplicitParams(@ApiImplicitParam(name = "deptno",value = "部门编号",required =true,dataType = "Integer") )
    @GetMapping("/Dept")
    public Dept getDeptInfo(@ApiParam("deptno") Integer deptno) {
        return deptService.queryDeptByDeptNo(deptno);
    }

}