Springdoc - 如何将 externalDocs 添加到 OpenAPI swagger UI 自动生成的文档

Question

所以我有一个 spring 引导项目，我刚刚将 OpenAPI Swagger UI 添加到其中。它会自动为我们所有的控制器和模型很好地生成文档。但我想添加一些额外的配置，例如此处所示的 externalDocs。

externalDocs:
    url: URL
    description: DESC

但是由于它是自动生成的，所以我没有用于 swagger 的 YAML。我尝试了以下方法通过 Bean 添加它，但没有成功。

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;

public class springShopOpenAPI{

    @Bean
    public OpenAPI springShopOpenAPI() {
           return new OpenAPI()
            .info(new Info().title("SpringShop API")
            .description("Spring shop sample application")
            .version("v0.0.1")
            .license(new License().name("Apache 2.0").url("http://springdoc.org")))
            .externalDocs(new ExternalDocumentation()
            .description("SpringShop Wiki Documentation")
            .url("https://springshop.wiki.github.org/docs"));
    }
}

如果需要，下面是我的Pom.xml。

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.2.28</version>
</dependency>

感谢您的任何建议。

Answer 1

您需要实现 OperationCustomizer 接口来添加外部链接。代码应如下所示

@Component
public class EndpointCustomizer implements OperationCustomizer {

    @Override
    public Operation customize(Operation operation, HandlerMethod handlerMethod) {
        // Will add the externalDocs to all the endpoints
        operation.externalDocs(new ExternalDocumentation().url("/resource").description("Link to resource"));
        
        return operation;
    }
}

您还可以执行其他逻辑以根据特定条件添加 externalDocs。定义 class 后，您需要在定义 OpenAPI Bean 的 class 中创建一个 API 组（springShopOpenAPI class 在你的情况下）。

@Bean
public GroupedOpenApi hideApis(EndpointCustomizer endpointCustomizer) {
    return GroupedOpenApi.builder().group("default") // or use null instead of default
            .addOperationCustomizer(endpointCustomizer)
            .build();
}

Answer 2

我需要做的就是添加 @Configuration 并更新我的 pom.xml 以具有以下内容。

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.4.4</version>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-webmvc-core</artifactId>
            <version>1.4.4</version>
        </dependency>

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class springShopOpenAPI{



    @Bean
    public OpenAPI customOpenAPI(){
        return new OpenAPI()
                .info(new Info().title("SpringShop API")
                        .description("Spring shop sample application")
                        .version("v0.0.1")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("SpringShop Wiki Documentation")
                        .url("https://springshop.wiki.github.org/docs"));
    }

}

Springdoc - 如何将 externalDocs 添加到 OpenAPI swagger UI 自动生成的文档

Springdoc - How do I add externalDocs to OpenAPI swagger UI auto generated documentation

spring-boot

swagger

openapi

springdoc-openapi-ui