Java - 如何直接从 openapi 3.0 规范生成 Swagger UI

Question

我有 yaml 格式的 openapi 3.0 规范和从中生成代码的应用程序。除了生成 swagger ui 外，一切正常。我使用 spring-fox 来生成它，但它似乎从控制器生成 swagger ui 2.0 版本，这些控制器是从 openapi 规范生成的。如何直接从我的 3.0 规范而不是从 3.0 openapi 规范生成的控制器生成 swagger ui？

Answer 1

好吧，我已经解决了这个问题（虽然解决方案很麻烦）。

首先，我添加了 swagger ui webjar -

        <plugin>

            <!-- Download Swagger UI webjar. -->

            <artifactId>maven-dependency-plugin</artifactId>

            <version>${maven-dependency-plugin.version}</version>

            <executions>

                <execution>

                    <phase>prepare-package</phase>

                    <goals>

                        <goal>unpack</goal>

                    </goals>

                    <configuration>

                        <artifactItems>

                            <artifactItem>

                                <groupId>org.webjars</groupId>

                                <artifactId>swagger-ui</artifactId>

                                <version>${swagger-ui.version}</version>

                            </artifactItem>

                        </artifactItems>

                        <outputDirectory>${project.build.directory}/classes</outputDirectory>

                    </configuration>

                </execution>

            </executions>

        </plugin>

然后我将我的 yaml 规范转换为 json 格式并将其复制到 swagger-ui webjar 目录：

            <plugin>

                <groupId>org.openapitools</groupId>

                <artifactId>openapi-generator-maven-plugin</artifactId>

                <version>4.0.0-beta3</version>

                <executions>                    

                    <execution>

                        <id>generate-spec</id>

                        <goals>

                            <goal>generate</goal>

                        </goals>

                        <configuration>

                            <inputSpec>${openapi-spec-file-location}</inputSpec>

                            <validateSpec>true</validateSpec>

                            <generatorName>openapi</generatorName>

                            <output>${project.build.directory}/classes/META-INF/resources/webjars/swagger-ui/${swagger-ui.version}</output>

                        </configuration>

                    </execution>

                </executions>

            </plugin>

接下来我们需要在 swagger-ui 中设置规范路径。根据swagger-ui API，我们可以传递specJSON 变量而不是 url。因此，要初始化此spec变量并编辑 swagger ui 渲染，我在 maven 中使用了替换插件：

            <plugin>

                <!-- Replace the OpenAPI specification example URL with the local one. -->

                <groupId>com.google.code.maven-replacer-plugin</groupId>

                <artifactId>replacer</artifactId>

                <version>1.5.3</version>

                <executions>

                    <execution>

                        <phase>prepare-package</phase>

                        <goals>

                            <goal>replace</goal>

                        </goals>

                    </execution>

                </executions>

                <configuration>

                    <includes>

                        <!-- Static index html with swagger UI rendering and OAS in JSON format. -->

                        <include>${project.build.directory}/classes/META-INF/resources/webjars/swagger-ui/${swagger-ui.version}/index.html</include>

                        <include>${project.build.directory}/classes/META-INF/resources/webjars/swagger-ui/${swagger-ui.version}/openapi.json</include>

                    </includes>

                    <regexFlags>

                        <regexFlag>CASE_INSENSITIVE</regexFlag>

                        <regexFlag>MULTILINE</regexFlag>

                    </regexFlags>

                    <replacements>

                        <!-- This replacement imports spec json variable into static html page. -->

                        <replacement>

                            <token>&lt;script&gt;</token>

                            <value>&lt;script src="./openapi.json"&gt; &lt;/script&gt;&lt;script&gt;</value>

                        </replacement>

                        <!-- This part replaces url input variable with spec variable. -->

                        <replacement>

                            <token>url:\s"https:\/\/petstore\.swagger\.io\/v2\/swagger\.json"</token>

                            <value>spec: spec</value>

                        </replacement>

                        <replacement>

                        <!-- This replacement initializes spec variable, that will be passed to swagger ui index.html. -->

                            <token>^\{</token>

                            <value>spec = {</value>

                        </replacement>

                    </replacements>

                </configuration>

            </plugin>

所以在构建后的这一步，我们得到了带有 swagger ui 的静态资源。最后要做的就是用 Spring 来服务它。

@Configuration

@EnableWebMvc

public class SwaggerConfiguration implements WebMvcConfigurer {

    @Override

    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        registry.addResourceHandler("/**")

                .addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/3.22.0/");

    }

    //this method was introduced just for convenient swagger ui access. Without it swagger ui can be accessed with /index.html GET call   

    @Override

    public void addViewControllers(ViewControllerRegistry registry) {

        registry.addViewController("/swagger-ui.html").setViewName("forward:/index.html");

    }

}

所以就是这样。如果您评论此答案并指出如何简化此过程，那就太好了。