773 Star 6.7K Fork 1.4K

GVP萧明/knife4j

 / 详情

添加SpringSecurity登录接口到knife4j中

Done
Opened this issue  
2022-11-30 22:50

有些场景我们需要手动将接口添加到knife4j中,SpringSecurity的用户名密码登录接口,无法通过这种注解方式生成api接口文档。这个时候如何将登录接口添加到knife4j中?
比如:在requestBody使用JSON传参

@Component
public class OwnSwaggerAddtion implements ApiListingScannerPlugin
{
    /**
     * 实现此方法可手动添加ApiDescriptions
     */
    @Override
    public List<ApiDescription> apply(DocumentationContext context)
    {
        Operation usernamePasswordOperation = new OperationBuilder(new CachingOperationNameGenerator())
                .method(HttpMethod.POST)
                .summary("用户名密码登录")
                .notes("用户登陆获取token")
                .consumes(Sets.newHashSet(MediaType.APPLICATION_JSON_VALUE))
                .produces(Sets.newHashSet(MediaType.APPLICATION_JSON_VALUE))
                .build();

        ApiDescription loginApiDescription = new ApiDescription("login", "/login", "登录接口", "描述", Arrays.asList(usernamePasswordOperation), false);

        return Arrays.asList(loginApiDescription);
    }

    /**
     * 是否使用此插件
     *
     * @param documentationType swagger文档类型
     * @return true 启用
     */
    @Override
    public boolean supports(DocumentationType documentationType)
    {
        return DocumentationType.OAS_30.equals(documentationType);
    }
}

这样只会显示
输入图片说明

Comments (10)

刘云飞 created任务

是要做什么?添加扩展接口?

springsecurity登录接口。需要自己在页面上添加接口文档和调试

是不是 需要knife4j 可以自动的将【springsecurity的登录接口】识别出来,并且在页面上显示?

是的,要不然没办法在页面上获取token。进行其他接口的调试

你这种自定义plugin的方式不是挺好的么

参数不出来 :joy:

你这个自定义plugin都搞出来了,添加参数很简单了啊,Operation实例赋值Parameter数组就好了

代码示例:

List<Parameter> parameters=new ArrayList<>();
parameters.add(new ParameterBuilder().name("username").modelRef(new ModelRef("String")).defaultValue("test").description("用户名").build());

parameters.add(new ParameterBuilder().name("password").modelRef(new ModelRef("String")).defaultValue("123").description("密码").build());

        Operation usernamePasswordOperation = new OperationBuilder(new CachingOperationNameGenerator())
                .method(HttpMethod.POST)
                .summary("用户名密码登录")
                .notes("用户登陆获取token")
//赋值参数
                .parameters(parameters)
                .consumes(Sets.newHashSet(MediaType.APPLICATION_JSON_VALUE))
                .produces(Sets.newHashSet(MediaType.APPLICATION_JSON_VALUE))
                .build();

输入图片说明

json方式则很麻烦,建议放弃

好的,谢谢

萧明 added
 
question
label
萧明 changed issue state from 待办的 to 已完成

使用Open-Api3的时候,直接引入以下Maven坐标,没有找到这个ApiListingScannerPlugin接口:

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.1.0</version>
</dependency>

是不是我有的坐标还没有引入,或者是open-api3用了另外的接口

@刘云飞 @liweitang @jessi

思路其实是一样的,springdoc也开放了两种级别的customizer接口:

  • GlobalOperationCustomizer:针对Operation级别的全局自定义扩展钩子函数,开发者可以对接口中每一个Operation进行扩展自定义实现,或调整,或修改,或增加扩展都行,Knife4j的部分增强特性就是基于此函数实现,可以参考代码Knife4jJakartaOperationCustomizer.java
  • GlobalOpenApiCustomizer:是针对整个OpenAPI级别的,开发者在分组或者分包后,得到的单个OpenAPI实例,开发者可以操纵全局的OpenAPI实例,该OpenAPI对象已经是springdoc解析过的实例对象,例如该issues中的需求,开发者只需要自定义创建新Operation对象,然后通过OpenAPI实例对象进行add添加即可完成此需求,部分扩展可以参考代码:Knife4jOpenApiCustomizer.java

Sign in to comment

Status
Assignees
Milestones
Pull Requests
Successfully merging a pull request will close this issue.
Branches
Planed to start   -   Planed to end
-
Top level
Priority
参与者(4)
118100 xiaoym 1578918321 8938296 li weitang 1712370212
Java
1
https://gitee.com/xiaoym/knife4j.git
git@gitee.com:xiaoym/knife4j.git
xiaoym
knife4j
knife4j

Search

344bd9b3 5694891 D2dac590 5694891