Swagger笔记

Swagger笔记 1、Swagger简介

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

支持在线同步API文档，不用手动编写API文档。支持Web页面的在线测试API，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

swagger官网：https://swagger.io/

2、Swagger使用步骤

导入依赖


    com.spring4all
    swagger-spring-boot-starter
    1.7.1.RELEASE

配置swagger

@Configuration
@EnableSwagger2  // 开启swagger
public class SwaggerConfig {
    
    // 这样就可以使用swagger的默认配置 
}

测试：访问localhost:8080/swagger-ui.html就可以访问默认的页面

3、Swagger配置信息

// 配置Docket的相关信息
@Bean
public Docket getDocket(){


    // 文档类型设置为documentationType.SWAGGER_2
    return new Docket(documentationType.SWAGGER_2)
            // 设置对应的swagger的api信息，参数是一个Contact对象
            // 默认是ApiInfo实体类
            .apiInfo(this.getApiInfo());
}

private ApiInfo getApiInfo(){
    // 文档的作者信息
    Contact contact = new Contact("xiaotanke", "http://www.yujiangg.com", "LHJ160414@163.com");
    return new ApiInfo(
            // 题目
            "测试的Swagger文档",
            // 描述
            "这是一个测试api文档",
            // 版本
            "v-1.0",
            // 作者网站
            "http://www.yujiangg.com",
            // 作者的个人信息
            contact,
            // 开源信息
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList()
    );
}

4、Swagger配置扫描

swagger默认是扫描项目的全部接口，即扫描项目中的所有controller中的接口，但是我们可以自定义扫描接口。

// 配置Docket的相关信息
    @Bean
    public Docket getDocket(){


        // 文档类型设置为documentationType.SWAGGER_2
        return new Docket(documentationType.SWAGGER_2)
                // 设置对应的swagger的api信息，参数是一个Contact对象
                // 默认是ApiInfo实体类
                .apiInfo(this.getApiInfo())
                // 自定义扫描接口，select()和build()是联合使用的，只能在之间配置
                // 两种方式，选择一种
                .select()
                // apis配置扫描接口范围
                
//                .apis(RequestHandlerSelectors.basePackage("com.xiaotanke.controller"))
                .apis(RequestHandlerSelectors.any())
//                .apis(RequestHandlerSelectors.none())
//                .apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
//                .apis(RequestHandlerSelectors.withClassAnnotation(Controller.class))
                // 扫描过滤请求下的接口
                
//                .paths(PathSelectors.ant("/admin
//                .apis(RequestHandlerSelectors.basePackage("com.xiaotanke.controller"))
                .apis(RequestHandlerSelectors.any())
//                .apis(RequestHandlerSelectors.none())
//                .apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
//                .apis(RequestHandlerSelectors.withClassAnnotation(Controller.class))
                // 扫描过滤请求下的接口
                
//                .paths(PathSelectors.ant("/admin/**"))
//                .paths(PathSelectors.any())
//                .paths(PathSelectors.none())
//                .paths(PathSelectors.regex("正则字符串"))
                .build();
    }

6、Swagger分组配置

根据API文档生成多个分组，每个组对应自己的文档。多个组实际就是多个Docket对象，每一个Docket对象就是一个组。

// 组名为B
@Bean
public Docket getBDocket(){
    return new Docket(documentationType.SWAGGER_2)
            // 组名
            .groupName("B");
}
// 组名为C
@Bean
public Docket getCDocket(){
    return new Docket(documentationType.SWAGGER_2)
            .groupName("C");
}
// 组名为D
@Bean
public Docket getDDocket(){
    return new Docket(documentationType.SWAGGER_2)
            .groupName("D");
}

7、Swagger注解配置

实体类注解

当扫描的接口其中一个返回了一个实体对象，那么在swagger的model中就会有对应实体的内容。

// lombok注解
@Data
@AllArgsConstructor
@NoArgsConstructor
// swagger实体的注释，会在swagger中显示
@ApiModel("用户实体类")
public class User {
    // 实体类的字段注释
    @ApiModelProperty("自然主键")
    private Integer id;
    @ApiModelProperty("用户名")
    private String userName;
    @ApiModelProperty("用户密码")
    private String password;
}

接口注释

@Controller
public class LoginController {


    // @ApiOperation 作用于方法上，注释某一个接口
    // @ApiParam 作用于参数，用作参数的注释
    @ApiOperation("测试接口")
    @GetMapping("/test1")
    public String test1(@ApiParam("用户名参数") String username){
        return username;
    }
}

接口测试

注释注解在作用上就是一个文档的说明，没有实际上的作用。增强文档的可读性，也便于测试接口。

Swagger笔记

Java相关栏目本月热门文章