Swagger添加额外接口

谁借莪１个温暖的怀抱￠ 2023-10-03 14:01 27阅读 0赞

通过 `ApiListingScannerPlugin` 机制实现。

### 示例 ###

由于 Spring Security 的登录、登出接口是通过Filter实现，导致 Swagger 无法获取其信息。这里手动将登录、登出接口注册到Swagger中，在Swagger-UI才能展示，方便调用。

/**
     * 由于 Spring Security 的登录、登出接口是通过Filter实现，导致 Swagger 无法获取其信息。
     * 这里手动将登录、登出接口注册到Swagger中，在Swagger-UI才能展示，方便调用。
     *
     * @author markix
     */
    @Component
    public class SpringSecurityApis implements ApiListingScannerPlugin {
        
    
        @Override
        public List<ApiDescription> apply(DocumentationContext documentationContext) {
        
            //登录接口
            //1.定义参数
            Parameter username = new ParameterBuilder()
                    .name("username")
                    .description("用户名")
                    .type(new TypeResolver().resolve(String.class))
                    .modelRef(new ModelRef("string"))
                    .parameterType("form")
                    .required(true)
                    .defaultValue("admin")
                    .build();
            Parameter password = new ParameterBuilder()
                    .name("password")
                    .description("密码")
                    .type(new TypeResolver().resolve(String.class))
                    .modelRef(new ModelRef("string"))
                    .parameterType("form")
                    .required(true)
                    .defaultValue("123456")
                    .build();
            //2.接口的每种请求方式(GET/POST...)为一个 Operation
            Operation loginOperation = new OperationBuilder(new CachingOperationNameGenerator())
                    .method(HttpMethod.POST)
                    .summary("登录")
                    .tags(Sets.newHashSet("Authentication"))
                    .responseMessages(Sets.newHashSet(new ResponseMessageBuilder().code(200).message("OK").build()))
                    .consumes(Sets.newHashSet(MediaType.MULTIPART_FORM_DATA_VALUE))
                    .produces(Sets.newHashSet(MediaType.APPLICATION_JSON_VALUE))
                    .parameters(Arrays.asList(username, password))
                    .build();
            //3.每个接口路径对应一个 ApiDescription
            ApiDescription loginDesc = new ApiDescription(null, "/login", "登录", Arrays.asList(loginOperation), false);
    
            //登出接口
            Operation logoutOperation = new OperationBuilder(new CachingOperationNameGenerator())
                    .method(HttpMethod.GET)
                    .summary("登出")
                    .notes("退出登录")
                    .tags(Sets.newHashSet("Authentication"))
                    .responseMessages(Sets.newHashSet(new ResponseMessageBuilder().code(200).message("OK").build()))
                    .build();
            ApiDescription logoutDesc = new ApiDescription(null, "/logout", "注销", Arrays.asList(logoutOperation), false);
    
            documentationContext.getTags().add(new Tag("Authentication", "登录、登出"));
    
            List<ApiDescription> apiDescriptionList = new ArrayList<>(Arrays.asList(loginDesc, logoutDesc));
            return apiDescriptionList;
        }
    
        @Override
        public boolean supports(DocumentationType documentationType) {
        
            return DocumentationType.SWAGGER_2.equals(documentationType);
        }
    
    }

效果图：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzMxNzcyNDQx_size_16_color_FFFFFF_t_70]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzMxNzcyNDQx_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/2a6b16d34c9340ab967f1d9eef20a9dc.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzMxNzcyNDQx,size_16,color_FFFFFF,t_70