Java Swagger集成 相关学习以及总结

Swagger 集成前的准备

Java Web 项目中Spring 环境

maven 依赖：

		<dependency>
            <groupId>io.swaggergroupId>
            <artifactId>swagger-parserartifactId>
            <version>1.0.46version>
        dependency>
        
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.7.0version>
        dependency>
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.7.0version>
        dependency>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Swagger 相关定义文件

自己任意创建一个文件(名称任意) 内容大致如下：
更多内容放到下面逐一加入
注意： 如果通过 Spring 的 xml 文件注入该类，那么 @Configuration 不用添加

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.support.XmlWebApplicationContext;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.paths.AbstractPathProvider;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import javax.servlet.ServletContext;

@Configuration
@EnableSwagger2
public class SwaggerXxxx {

	// 总的接口文档信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("YvYvMy API").description("YvYv My Description")
                .contact(new Contact("YvYv", "http://www.YvYv.org", "XXXxxxxx")).version("2.0.0").build();
    }

	// 要加载的接口信息  以及扫描的接口路径等
    @Bean
    public Docket myApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                					// 请求处理选择器        // 通过类注解 注解叫 MyApiAn
                .apis(Predicates.or(RequestHandlerSelectors.withClassAnnotation(MyApiAn.class),
                		// 或                   // 方法上携带注解 MyApiAn 的
                        RequestHandlerSelectors.withMethodAnnotation(MyApiAn.class)))
                .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

接口信息的理解：

类似于构造函数以及 Builder 方式，链式创建对象；


鼠标移动到 Contact the developer 后查看右下角可以看到邮箱地址

打开后最下方会出现版本信息

在 @Bean 中扫描指定方法或路径的方式

RequestHandlerSelectors 用于选择 对应请求的选择器，相当于过滤：

指定单个时直接如下：

...........
    .apis(RequestHandlerSelectors.withClassAnnotation(MyApi.class))
...........
1
2
3

上面是通过类上的注解扫描的，还有几种常见方式如下：

通过包路径选择：
即某个包路径下扫描

.apis(RequestHandlerSelectors.basePackage("cn.xxxx.xxxx.xxx.xxcontroller"))
.paths(PathSelectors.any())
.build();
1
2
3

通过方法上的自定义注解选择：

.apis(RequestHandlerSelectors.withMethodAnnotation(MyApiAn.class))
1

需要多个时如上面第一个案例中内容：

.apis(Predicates.or(RequestHandlerSelectors.withClassAnnotation(MyApiAn.class),
     RequestHandlerSelectors.withMethodAnnotation(MyApiAn.class)))
1
2

多个Bean ，即存在自定义的Api 分组时的写法

swagger 是可以通过 group 来区分多个 切换页面的，即不同的 group 下放置不同的人为分类下的接口，在实际业务开发也是很常见的，可能通过接口开放的对象，或者接口实际业务领域来区分等等

@Bean
    public Docket devApi() {

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(Predicates.or(RequestHandlerSelectors.withClassAnnotation(Myapi.class),
                        RequestHandlerSelectors.withMethodAnnotation(Myapi.class)))
                .build()
                // 分组名
                .groupName("group1");
    }
1
2
3
4
5
6
7
8
9
10
11

添加组名后将可以通过切换组名切换到不同的 Swagger 文档页

指定个别Bean 的 pathProvider

pathProvider 即 Swagger 接口文档的最下方都会有

即，我们上面提供的所有接口实际上都是脱离应用环境上下文的，直接的某一个或者某些直接映射到我们的Controller 的各个请求接口上，实际上请求时应用往往会带有应用上下文（context）的前缀。

正常的请求为 请求地址 + 端口 + 环境上下文 + 实际映射路径 然后是我们的参数等
当我们不指定 Bean 的 pathProvider 时，将会获取默认的环境上下文前缀，如果一律都是默认的那么这个就无需设置，否则需要添加 修正。
一个较为完整的例子：

    @Bean
    public Docket myApi() {

        ServletContext servletContext =
                ((XmlWebApplicationContext) SpringTool.getApplicationContext()).getServletContext();
        String bathPath =
                Strings.isNullOrEmpty(servletContext.getContextPath()) ? "/" : servletContext.getContextPath();

        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(Predicates.or(RequestHandlerSelectors.withClassAnnotation(DevAPI.class),
                        RequestHandlerSelectors.withMethodAnnotation(DevAPI.class)))
                .build()
                .groupName("groupName1")
                .pathProvider(new AbstractPathProvider() {
                    @Override
                    protected String applicationPath() {
                        return bathPath + "/api/Ar/";
                    }

                    @Override
                    protected String getDocumentationPath() {
                        return bathPath + "/api/Ar/";
                    }
                }).useDefaultResponseMessages(false);
    }
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

其中 SpringTool.getApplicationContext() 的 SpringTool 为自定义类，实际上为一个实现了 ApplicationContextAware 的类，用于获取应用上下文对象；
一般都是如下定义的, 如果需要顺便有介绍
ApplicationContextAware 获取环境上下文

Swagger 注解介绍

swagger 开发时的注解 添加到已有接口上的注解

注意

如果项目中存在继承 HandlerInterceptorAdapter 的，且重写了 preHandle 方法，说明存在请求拦截，那么需要对 swagger 放行，否则请求将被拦截；
类似如下写入，其他的拦截照常