Swagger2的学习

Swagger依赖

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

@Configuration
@EnableSwagger2 //开启使用swagger2（swagger是老版的）
public class SwaggerConfiguration {//使用自定义配置
    
    //使用docket实例用于取代swagger原本的配置。
    @Bean
    public Docket docket () {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
            	.groupName("grp1")//设置分组
            	.enable(true)
            	.select()
          	.apis(RequestHandlerSelectors.basePackage("com.zm.controller"))
            	.paths(PathSelectors.any())
            	.build();
    }
    
    private ApiInfo apiInfo() {
        
        Contact DEFAULT_CONTACT = new Contact("作者名:zm", "指定的某个url", "作者email");
        
        return new ApiInfo("标题：我的Swagger-Api文档", 
                           "本文档描述信息", "版本：1.0", 
                           "项目组织网址（一个url）", 
                           DEFAULT_CONTACT, 
                           "Apache 2.0", 
                           "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

Swagger的配置详解

/**
* Docket对象说明
*/
// Docket构造对象说明
/**
1、DocumentationType, 案例类型，一般取 SWAGGER_2
2、ApiInfo(),用于配置swagger的外部描述信息，该对象仅有一个构造方法
3、enable(boolean)：默认为true代表配置有效，可修改为false。
4、groupName(“grp1”)：用于设置分组,同一配置类下可以有多个docket，每个docket拥有一个组。
5、select(), 使用docket对象的select()进行构造配置。
	(1)apis()：用于配置要扫描接口的方式，其接受参数是一个函数式接口：Predicate selector。
		这里使用RequestHandlerSelectors.basePackage配置为扫描包：
	示例：
	RequestHandlerSelectors.basePackage("com.lk.controller") 扫描 com.lk.controller
	RequestHandlerSelectors.withClassAnnotation(RestController.class) 扫描 RestController注解
	(2)paths()：用于配置过滤路径，其接受参数是一个函数式接口：Predicate selector。这里使用PathSelectors.ant(“/book/**”)，表示筛选com.zm.controller包下访问接口为/book/下的接口。
	示例：
	PathSelectors.ant(“/book/**”) 访问接口为/book/路径的接口
	PathSelectors.any() 扫描全部接口
6、securitySchemes， 配置安全模式
7、securityContexts() 配置安全上下文
8、 globalResponseMessage() 全局返回信息
	示例：.globalResponseMessage(RequestMethod.GET, responseMessageList)；
*/

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

    /**
     * 安全上下文
     */
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContextList = new ArrayList<>();
        List<SecurityReference> securityReferenceList = new ArrayList<>();
        securityReferenceList.add(new SecurityReference("Authorization", scopes()));
        securityContextList.add(SecurityContext
                .builder()
                .securityReferences(securityReferenceList)
                .forPaths(PathSelectors.any())
                .build()
        );
        return securityContextList;
    }

    private AuthorizationScope[] scopes() {
        return new AuthorizationScope[]{new AuthorizationScope("global", "accessAnything")};
    }

 //全局返回信息
  List<ResponseMessage> responseMessageList = new ArrayList<>();
        responseMessageList.add(new ResponseMessageBuilder().code(ResultEnum.SUCCESS.getCode()).
                message(ResultEnum.SUCCESS.getMessage()).build());


/**
ApiInfo 对象，
1 contact对象：用于配置作者信息，再ApiInfo类中同样提供了Contac类对象的构造
示例：
*/
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("接口文档")
                .contact(new Contact("作者姓名", "http://test.lk.cool", "XXXXXx@gmail.com"))
                .description("Swagger动态接口文档")
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .version("Demo")
                .build();
    }

swagger注释注解

Controller类上
@Api(“xxx”)：作用在控制层类上
@ApiOperation(“xxx”)：作用于方法添加注释

入参出参
单个
@ApiParam(“xxx”)：作用于控制层接口参数添加注释
VO类上
@ApiModel(“xxx”)：给控制层返回的实体类对象添加注释
@ApiModelProperty(“xxx”)：给字段添加注释

默认访问地址
http://localhost:9110/swagger-ui.html