Swagger

参考：Swagger 3.0使用教程

Swagger原理

Swagger3使用

概述

代码文档，更新接口，前后端分离，减少前后端沟通成本，各个参数的含义，需要什么参数，错误码含义，请求头，代码和文档和为一体，方便测试接口，restful API的描述格式，是一个API管理工具，

• 使用的是Swagger3
• 添加方法的中文注解，@Operation
• 添加参数描述，@APiImplicitParam（单个参数的）@ APiImplicitParams(多个参数的情况)，但是这这个注解的约束是针对Swagger层的，是在Swagger测试页面是有效，但是和方法本身逻辑是不同的，如果用postman测试，可能就不在有这样的约束。（例如在这个注解说明参数必须存在等），这里在Swagger3中可以使用@Parameter注解实现，不然可能会有一些小bug
• 异常情况状态码说明，@APIResponses
• 不想生成API接口的方法上加@ApiIgnore
• 也可以在model中加注解，描述这个model的一些信息，例如这个类是干嘛的，属性的含义，@APIModel放在类上，@APIModelProperty属性上
• 生产环境下，设置swagger-ui的enabled值为false,
• 导入依赖后，可以直接使用，因为有自动配置类，不需要加注解@enableopenAPI

操作

注意Springboot版本，我的是2.1.8，在2.1.x版本中，需要修改spring-plugin-core版本，包版本不一致。如果是2.3.x版本，直接到Swagger依赖就行。

1、引入依赖

		<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
		<dependency>
            <groupId>org.springframework.plugin</groupId>
            <artifactId>spring-plugin-core</artifactId>
            <version>2.0.0.RELEASE</version>
        </dependency>

2、设置拦截器过滤：

• 方法一：在securityconfig中将Swagger资源的目录添加上。

@Override
    public void configure(WebSecurity web) throws Exception {
        web.ignoring().antMatchers("/css/**", "/js/**", "/index.html", "/img/**", "/fonts/**", "/favicon.ico", "/verifyCode"
                ,"/swagger**/**","/webjars/**","/v3/**","/doc.html");
    }

因为端口上都有spring security过滤器拦截请求，可以将一些请求也放在上面的资源过滤中，调试。

• 方法二：让swaggerconfig实现webmvccofigurer，重写addInterceptors拦截器

/**
     * 通用拦截器排除swagger设置，所有拦截器都会自动加swagger相关的资源排除信息
     */
    @SuppressWarnings("unchecked")
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        try {
            Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
            List<InterceptorRegistration> registrations = (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
            if (registrations != null) {
                for (InterceptorRegistration interceptorRegistration : registrations) {
                    interceptorRegistration
                            .excludePathPatterns("/swagger**/**")
                            .excludePathPatterns("/webjars/**")
                            .excludePathPatterns("/v3/**")
                            .excludePathPatterns("/doc.html");
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

一般接口API调试都是在开发环境中。

访问接口：http://ip:port/swagger-ui/index.html

3、添加授权信息

securitySchemes(securitySchemes())
securityContexts(securityContexts())

//设置授权信息
    private List<SecurityScheme> securitySchemes(){
        ApiKey apikey = new ApiKey("BASE_TOKEN","token",In.HEADER.toValue());
        return Collections.singletonList(apikey);
    }

    //授权信息全局应用
    private  List<SecurityContext> securityContexts(){
        return Collections.singletonList(
                SecurityContext.builder()
                        .securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")})))
                        .build()
        );
    }

原理

• Swagger的annotation主要分为两类，一类是对model，一类是对API

• 文档如何分组

一个项目中分为前台，后台、APP端、小程序端，分组实现。

Docket 用了配置分组，如果分别两个类返回Docket对象，就会有两个分组

• 如何添加授权信息

因为项目中有spring security 权限认证，可以在Swagger中配置认证信息，每次请求上都会默认携带上token。

在Docket中有securitySchemes()和securtyContexts()指定授权信息。

Tips

状态码：

• 200 ： OK
• 401：Unauthorized
• 403：Forbidden
• 404：Not found
• 500：Failure