【项目实训】Swagger2

当前，前后端分离已是主流，接口文档的编写就显得尤为重要了

但对后端来说，写文档实在是一种巨大的心智负担（注释都不写，写啥文档：）

自己手动写文档的方式不仅是初期写的时候很麻烦，而且后续维护也会很大困难（试想你后端接口改了个参数，但接口文档没及时更新，估计前端已经口吐芬芳了），更别说手动写的方式还很容易写错，实在是吃力不讨好。

于是swagger横空出世

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。

swagger的优点有很多，在我看来，主要有如下：

1.代码侵入性低，基本只需要写注解

2.自动生成文档，于是接口变化不需要你去维护文档编写

3.不仅仅是文档，同时也是测试工具

代码

引入依赖

        <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>

配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        List<Parameter> parameters = new ArrayList<>();
        parameters.add(new ParameterBuilder()
                .name("token")
                .description("认证token")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启
                //.enable(false)
                .select()
                //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(security())  //统一填写一次token
                .securityContexts(securityContexts())
                .globalOperationParameters(parameters);
    }

    private List<ApiKey> security() {
        List<ApiKey> apiKeyList = new ArrayList<>();
        apiKeyList.add(new ApiKey("token", "token", "header"));
        return apiKeyList;
    }

    private List<SecurityContext> securityContexts()
    {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build());
        return securityContexts;
    }

    private List<SecurityReference> defaultAuth()
    {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("token", authorizationScopes));
        return securityReferences;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("不良事件管理系统接口文档")
                //文档描述
                .description("")
                //服务条款URL
//                .termsOfServiceUrl("http://localhost:8080/")
                //版本号
                .version("1.0.0")
                .build();
    }
}

上述代码除了基本配置外，我另外对全局的token（header）做了设置

效果如下

可以做全局的设置

也可以在每个接口作为参数设置

swagger的一些常用注解：

@Api 用在类上，说明该类的作用。

@ApiModel 用在类上，表示对类进行说明，用于实体类中的参数接收说明。

@ApiModelProperty() 用于字段，表示对 model 属性的说明。

@ApiParam 用于 Controller 中方法的参数说明。