在上一张的项目中创建SwaggerConfig，进行配置文档内容。
1 配置基本信息
Docket：摘要对象，通过对象配置描述文件的信息。
apiInfo:设置描述文件中info。参数类型ApiInfo
select():返回ApiSelectorBuilder对象，通过对象调用build()可以创建Docket对象
ApiInfoBuilder：ApiInfo构建器。
package com.example.demo.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class SwaggerConfiguration {
/**
* 创建Docket类型的对象。并使用spring容器管理。
* Docket是Swagger中的全局配置对象。
* @return
*/
@Bean
public Docket docket(){
Docket docket = new Docket(DocumentationType.SWAGGER_2);
// API帮助文档的描述信息。 information
ApiInfo apiInfo =
new ApiInfoBuilder()
.contact( // 配置swagger文档主体内容。
new Contact(
"不死鸟", // 是文档的发布者名称
"http://www.bjsxt.com", // 是文档发布者的网站地址。企业网站
"[email protected]") // 文档发布者的电子邮箱
)
.title("swagger框架学习DEMO") //框架title
.description("Swagger框架学习帮助文档详细描述-Swagger框架是一个用于开发RestAPI帮助文档的框架") //框架描述
.version("1.1") //版本号
.build();
// 给docket上下文配置api描述信息。
docket.apiInfo(apiInfo);
return docket;
}
}
显示效果如下：
2 设置扫描的包
可以通过apis()方法设置哪个包中内容被扫描，直接对SwaggerConfig进行修改。
docket = docket
.select() // 获取Docket中的选择器。 返回ApiSelectorBuilder。构建选择器的。如：扫描什么包的注解。
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.build();设置以后如下图，只有com.example.demo.controller中的接口被扫描。
3 自定义注解设置不需要生成接口文档的方法
3.1自定义注解
注解名称随意，我这边新建MyAnnotation4Swagger。
package com.example.demo.anno;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* @Target - 描述当前的注解可以定义在什么资源上。
* 属性 value
* - 定义具体的资源。 包括：
* - ElementType.METHOD 可以定义在方法上
* - ElementType.TYPE 可以定义在类型上
* - ElementType.FIELD 可以定义在属性上
* - ElementType.PARAMETER 可以定义在方法参数上
* @Retention - 当前注解在什么时候有效
* 属性 value
* - 定义具体的生效标记
* - RetentionPolicy.RUNTIME - 运行时有效
* - RetentionPolicy.SOURCE - 源码中有效
* - RetentionPolicy.CLASS - 字节码有效
*/
@Target(value={ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation4Swagger {
// 自定义注解中的属性。相当于 @MyAnnotation4Swagger(value="")
String value() default "";
}
3.2 添加规则
- 通过public ApiSelectorBuilder apis(Predicate<RequestHandler> selector)可以设置生成规则。
- public static <T> Predicate<T> not(Predicate<T> predicate) :表示不允许的条件。
- withMethodAnnotation：表示此注解是方法级别注解。
.apis(
Predicates.and(
Predicates.not( // 取反。false -> true true -> false
RequestHandlerSelectors.withMethodAnnotation( // 当方法上有注解的时候返回true
MyAnnotation4Swagger.class) // 方法上有什么注解的时候返回true
)
)
)
3.3 使用注解
在不需要生成接口文档的接口上增加注解 @MyAnnotation4Swagger，该方法将不会被Swagger进行生成在接口文档中。
启动后效果如下：
4 设置路径范围
通过public ApiSelectorBuilder paths(Predicate<String> selector)可以设置满足什么样规则的url被生成接口文档。可以使用正则表达式进行匹配。
下面例子中表示只有以/swagger/或者/swagger2/开头的url才能被swagger生成接口文档。
如何希望全部扫描可以使用paths(PathSelectors.any())
.paths(
Predicates.or( // 多个规则符合任意一个即可通过。
PathSelectors.regex("/swagger/.*"), // 使用正则表达式，约束生成API文档的路径地址。
PathSelectors.regex("/swagger2/.*")
)
)
运行后效果如下：
