网络知识 娱乐 swagger2 配置访问路径_swagger2---程序猿的便捷神器

swagger2 配置访问路径_swagger2---程序猿的便捷神器

发布: 2023年2月14日 10:17:50

这个框架有什么好处，为什么要学它？

1、为前端提供接口数据。在前后端分类的项目中，前后端数据同步问题一直是一个头疼的问题，导致前后端人员经常意见不合，撕b甚至大打出手

1474715c3f03316b8ddc2d84f95f28ec.png

提供接口数据

2、实时更新文档。在我们增加一个字段或者改变某些信息的时候总是没有实时更新文档的习惯，导致后期维护造成很大的困扰，占用不必要的工作时间。

35aefbbe9219799b635e1bd5a1bfa9c5.png

可以清楚看到各个接口及意义，后端改，实时同步

3、可以在线测试。这个功能相当于postman，可以自己模拟参数，然后测试。

输入具体的参数后，点击Execute运行测试

bd649c0fd0a3015ee5bee2f8b138e9f0.png

Swagger2的出现就是为了从根本上解决上述问题。它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务

好处说完了，怎么使用呢？

其实很简单，引入一个pom依赖，写一个配置类就可以使用了。下面为我实操过程中的笔记

1、首先创建一个spring boot项目

这个就不详细展开了，IDEA有专门的模板，maven目录结构就可以

2、引入pom依赖


io.springfox
springfox-swagger2
2.9.2

 

io.springfox
springfox-swagger-ui
2.9.2

3、编写配置为swagger2，使用注解@EnableSwagger2

@EnableSwagger2
@Configuration
publicclassSwagger2Config{
 }

4、访问地址

http://localhost:9000/swagger-ui.htmllocalhost:9000

页面就出来了， 看似没有配置，实际使用的为默认配置

2519ff59b8fd3bd4dee4ee5cdf3a9fde.png

接下来就可以进行自定义配置了，也就是自我探索阶段。

可以先验证下注释怎么生成的

首先新建一个pojo类，我用的User类

package swagger.demo.pojo;


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

/**
 * @author dali
 * @date 2020-12-02 16:38
 * @Description
 */

public class User {
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty("电话")
    private String phone;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPhone() {
        return phone;
    }

    public void setPhone(String phone) {
        this.phone = phone;
    }
}

因为它默认扫描为全部的包，重启启动后可以看见如图

1fe47b5c4f2841df40f087f5917f89cb.png

这里面的注解都是@APIxxx,感兴趣的可以一一测试

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

下面说一下，配置类中如何进行自定义配置

package swagger.demo.config;

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;

/**
 * @author dali
 * @date 2020-12-02 15:08
 * @Description
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    //配置swagger的实例
    @Bean
    public Docket docket(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                //这个可以自定义页面出现的标题，描述等信息
                .apiInfo(this.apiInfo())
                //是否开启swagger2，可以用作环境判断使用
                .enable(true)
                //筛选
                .select()
                //扫描的包
                .apis(RequestHandlerSelectors.basePackage("swagger.demo.controller"))
                //构建项目
                .build();
    }


    public ApiInfo apiInfo(){
        Contact contact = new Contact("bigli","url","123@qq.com");
        return new ApiInfo("标题",
                "描述",
                "v1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

d379a2ca504b89568f9ccbab5182f6b9.png

其中的apiInfo这个方法改变的是这块内容

需要写Docket这个方法来实现自定义配置，我只是使用了一部分配置，可以自行探索，主要应该学会举一反三，到具体项目中在变动

总结：swagger2就相当于一个实时同步文档，给前端提供接口的插件。将平常写注释前面加个注解就可以了，非常的方便，但是生产环境为了安全和运行效率，需要关闭

思考一个问题，我们该如何让他在生产环境中关闭，在开发或者其他环境中中开启？

1、定义环境，在配置文件中。以application.properties为例

spring.profiles.active=dev

2、获取到当前环境

Profiles profile = Profiles.of("dev");

3、用当前获取的环境判断有没有

boolean b = environment.acceptsProfiles(profile);

4、传入enable方法中

相关文章