请让我后端为前端打开一扇窗--swagger

Swagger 初探

前后端分离时代的产物

从早期word提前约定，到postman方便前后端解耦，到swagger实现接口展示更新，再到目前流行的apifox（相当于Postman + Swagger + Mock），技术不断更新发展。本章博客记录swagger的基本用法。

新建一个springboot项目，引入web依赖，写一个简单的hello接口。

引入依赖

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

注意到下面那个依赖，名字里带ui，猜想可能是接口展示界面的风格。搜了一下，下面提供两个不同皮肤，可以把上面那个依赖改成下面的。

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

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
    <groupId>com.github.caspar-chen</groupId>
    <artifactId>swagger-ui-layer</artifactId>
    <version>1.1.3</version>
</dependency>

同时默认访问** http://localhost:8080/swagger-ui.html**，也应该分别改成http://localhost:8080/doc.html和http://localhost:8080/docs.html**

swagger配置,新建一个配置类

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

@Configuration
@EnableSwagger2  //开启swagger2
public class SwaggerConfig {
    
}

此时无需再加配置，启动后已经可以访问http://localhost:8080/swagger-ui.html进行访问。

配置封面(在conf中)

    //配置文档信息
    private ApiInfo apiInfo() {

        //作者信息   
        Contact contact = new Contact("njuptwly","www,njuptwly.com","1152936469@qq.com");

        return new ApiInfo(
                "Swagger学习", // 标题
                "学习演示如何配置Swagger", // 描述
                "v1.0", // 版本号
                "www.njuptwly.com", // 组织链接
                 contact, // 联系人信息
                "Apach 2.0 ", // 许可
                "www.njuptwly.com", // 许可连接
                new ArrayList<>() // 扩展
        );
    }

    //将 Docket 实例关联上 apiInfo()
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

改成自己的之后可以运行看一下效果.

配置扫描接口(conf中)

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.swagger.demo.controller"))//配置包路径进行选择
                .build();
    }

其他选择方式如下

@Bean
public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否启动swagger 如果是false则不能在浏览器中使用
                .enable(true)
                .select()
                //RequestHandlerSelectors.  配置要扫描的方式(+后面的方式)
                //basePackage()   指定要扫描的包
                //any()   扫描全部
                //none()  不扫描
                //withClassAnnotation()  扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation()   扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.swagger.demo.controller"))
                //.paths() .过滤URL(PathSelectors.)
                //any() 任何请求都扫描
                //none() 任何请求都不扫描
                //ant()	通过ant控制
                //regex() 通过正则表达式控制
                .paths(PathSelectors.ant("/demo/**"))
                .build();
 }

swagger开关

只在生产环境显示

//设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev", "test");
        //通过environment.acceptsProfiles判断是否处于自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Ferao-group")
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                //配置要扫描的接口
                .apis(RequestHandlerSelectors.basePackage("com.ferao.controller"))
                .paths(PathSelectors.ant("/users/**"))
                .build();
    }

api分组

 @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("user_api");
    }
@Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("admin_api");
    }

实体类注解

@ApiModel("用户实体")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

在所有返回值为User上进行显示

@ApiModel  //为类添加注释,作用在模型类上

@ApiModelProperty(value = "xxx属性说明",hidden = true)	//作用在类方法和属性上，hidden设置为true可以隐藏该属性

接口注解

@Api(tags = "")	//作用在模块类上
@ApiOperation("xxx接口说明")	//作用在接口方法上
@ApiParam("xxx参数说明")	//作用在参数、方法和字段上，类似@ApiModelProperty

@ApiOperation("获取用户名的接口")
@ApiResponses({
        @ApiResponse(code=200,message="请求成功"),
        @ApiResponse(code=500,message="系统异常")
})
@PostMapping("/getUsername")
@ResponseBody
public String getUsername(@ApiParam("用户名")String username){
    return username;
}

对参数的注解还有

@ApiImplicitParams({
     @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "用户名", required = true, paramType = "query", dataType = "String")
    })
})
//paramtype 还有header,path,body