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

【问题标题】：Springdoc - How do I add externalDocs to OpenAPI swagger UI auto generated documentationSpringdoc - 如何将 externalDocs 添加到 OpenAPI swagger UI 自动生成的文档
【发布时间】：2020-08-25 15:22:56
【问题描述】：

所以我有一个 Spring Boot 项目，我刚刚添加了 OpenAPI Swagger UI。它会为我们所有的控制器和模型自动生成非常好的文档。但我想添加一些额外的配置，例如这里显示的 externalDocs。

externalDocs:
    url: URL
    description: DESC

但由于它是自动生成的，因此我没有用于招摇的 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>

感谢您的任何建议。

【问题讨论】：

你在使用 Springdoc 等框架吗？
我正在使用 springdoc-openapi-ui v1.2.28

标签： spring-boot swagger openapi springdoc-openapi-ui

【解决方案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。定义类后，您需要在定义 OpenAPI Bean 的类中创建一个 API 组（在您的情况下为 springShopOpenAPI 类）。

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

【讨论】：

如果我没有创建 OpenAPI Bean 的类，我应该在哪里添加 bean？或者 OpenAPI bean 类应该是什么样的>
@Dylan 在您的情况下该类已经存在，即springShopOpenAPI。那里有一个返回 OpenAPI 对象的 bean。这就是我所指的。
我收到一个错误，指出组具有私有访问权限，但将其更改为 setGroup 意味着 addOperationCustomizer 不存在
您应该使用group 而不是setGroup。如果您查看源代码，您会知道 setGroup 已被弃用，而应使用 group 代替。对于私人问题，请为您制作的两个文件分享一个 github gist。
更多讨论，我们可以在下面的聊天室继续chat.stackoverflow.com/rooms/220444/springdoc-clarification

【解决方案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"));
    }

}

【讨论】：