swagger

swagger如何使用？
第一步：导入swagger依赖包

    io.springfox
    springfox-swagger2
    3.0.0


    io.springfox
    springfox-swagger-ui
    3.0.0


    com.github.xiaoymin
    knife4j-spring-boot-starter
    3.0.2

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

第二步：创建swagger配置文件
在这里插入图片描述

@Configuration
@EnableSwagger2
@EnableKnife4j
@Profile({“dev”, “test”})
public class SwaggerConfig {
/**
* 系统基础配置
*/
@Autowired
private RpcsConfig rpcsConfig;

/**
 * 创建API
 */
@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .pathMapping("/dev-api")
            // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
            .apiInfo(apiInfo())
            // 设置哪些接口暴露给Swagger展示
            .select()
            // 扫描所有有注解的api，用这种方式更灵活
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            // 扫描指定包中的swagger注解
            //.apis(RequestHandlerSelectors.basePackage("com.ryi.rpcs.project.tool.swagger"))
            // 扫描所有 .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build()
            /* 设置安全模式，swagger可以设置访问token */
            .securitySchemes(securitySchemes())
            .securityContexts(securityContexts());
}

/**
 * 安全模式，这里指定token通过Authorization头请求头传递
 */
private List securitySchemes() {
    List apiKeyList = new ArrayList();
    apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
    return apiKeyList;
}

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

/**
 * 默认的安全上引用
 */
private List defaultAuth() {
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    authorizationScopes[0] = authorizationScope;
    List securityReferences = new ArrayList<>();
    securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
    return securityReferences;
}

/**
 * 添加摘要信息
 */
private ApiInfo apiInfo() {
    // 用ApiInfoBuilder进行定制
    return new ApiInfoBuilder()
            // 设置标题
            .title("标题：快速预安检系统_接口文档")
            // 描述
            .description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
            // 作者信息
            .contact(new Contact(rpcsConfig.getName(), null, null))
            // 版本
            .version("版本号:" + rpcsConfig.getVersion())
            .build();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

}

4、注解及其说明
@Api : 用在类上，描述该类的主要作用。

@ApiOperation：用在方法上，给API增加方法描述。

@ApiImplicitParams : 用在方法上，包含一组参数描述。

@ApiImplicitParam：用来注解来给方法入参增加描述。

@ApiResponses：用于表示一组响应。

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息。

code：数字，例如500
message：信息，例如"请求参数异常"
response：抛出异常的类

@ApiModel：用在返回对象类上，描述一个Model的信息（一般用在请求参数无法使用ApiImplicitParam注解进行描述的时候）。

@ApiModelProperty：描述一个model的属性。

5.关闭Swagger有两种方式
方式一：
在Swagger2Config上使用@Profile注解标识，@Profile({“dev”,“test”})表示在dev和test环境才能访问swagger-ui.html，prod环境下访问不了。

方式二：
在Swagger2Config上使用@ConditionalOnProperty注解，

@ConditionalOnProperty(name = “swagger.enable”, havingValue = “true”)

表示配置文件中如果swagger.enable =true表示开启。所以只需要在开发环境的配置文件配置为true，生产环境配置为false即可。

个人建议使用第一种方法。

swagger但是说实在的太难看了，但是有一个增强工具knife4j,只需要引入依赖就能用