maven - 使用 maven 为 Micronaut Swagger

Question

我想从 Spring Boot 2 切换到 Micronaut 框架。我在 Swagger 设置上苦苦挣扎。

在 Spring Boot 2 项目中，我有以下依赖项:

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.6.1</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.6.1</version>
    </dependency>

和 SwaggerConfig.class:

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket swagger() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(getApiInfo())
            .select()
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo getApiInfo() {
        return new ApiInfo("test",
            "",
            "",
            "",
            new Contact("", "https://test.test", ""),
            "",
            "");
    }
}

它可以完美地启动 swagger-ui 以及 Spring Boot 2 应用程序。

我应该将哪些依赖项添加到 maven 以及我应该创建哪些类才能为 Micronaut 项目获得相同的结果？

Answer 1

假设已经创建了应用程序，请将以下内容添加到 pom.xml

<dependency>
  <groupId>io.swagger.core.v3</groupId>
  <artifactId>swagger-annotations</artifactId>
  <version>${swagger.version}</version>
  <scope>compile</scope>
</dependency>

其中属性 swagger.version 设置为 2.0.3

在 maven-compiler-plugin 中将以下内容添加到 annotationProcessorPaths

<path>
  <groupId>io.micronaut.configuration</groupId>
  <artifactId>micronaut-openapi</artifactId>
  <version>${micronaut.version}</version>
</path>

然后将以下内容添加到您的 micronaut 路由器部分。

micronaut:
    router:
        static-resources:
            swagger:
                paths: classpath:META-INF/swagger
                mapping: ${application.api.swagger.path}/**

如果您使用下面的配置，这将公开您在编译期间生成的 swagger/oas yml 文件。您当然可以更改 ${application.api.swagger.path}只是 /api-docs/swagger或者你喜欢的东西。
如文档中所述，您还可以执行以下 --features=swagger-java在您最初创建项目时添加上述依赖项。

如果您想从应用程序本身呈现 api 规范，那么您需要添加更多代码。下面的示例可能比它需要的更加充实，但出于我的目的，该应用程序充当了 swagger/oas 规范的中央渲染器。

首先为您的 Swagger 需要添加一个 Controller ，并使用 @Hidden 注释 Controller 以确保它不会被注释处理器处理。

@Hidden
@Controller("/api")
public class SwaggerController {

    @Inject
    SwaggerConfig config;

    @View("swagger/index")
    @Get
    public SwaggerConfig index() {
        return config;
    }
}

然后添加以下配置类，它从下面绑定(bind)属性

@ConfigurationProperties(SwaggerConfig.PREFIX)
public class SwaggerConfig {

    public static final String PREFIX = "application.api.swagger";

    private String version;
    private String layout;
    private boolean deepLinking;
    private List<URIConfig> urls;

    public String getVersion() {
        return version;
    }

    public void setVersion(String version) {
        this.version = version;
    }

    public String getLayout() {
        return layout;
    }

    public void setLayout(String layout) {
        this.layout = layout;
    }

    public boolean isDeepLinking() {
        return deepLinking;
    }

    public void setDeepLinking(boolean deepLinking) {
        this.deepLinking = deepLinking;
    }

    public List<URIConfig> getUrls() {
        return urls;
    }

    public void setUrls(List<URIConfig> urls) {
        this.urls = urls;
    }


    @ConfigurationProperties(URIConfig.PREFIX)
    public static class URIConfig {

        static final String PREFIX = "urls";

        private String name;
        private String url;

        public String getName() {
            return name;
        }

        public void setName(String name) {
            this.name = name;
        }

        public String getUrl() {
            return url;
        }

        public void setUrl(String url) {
            this.url = url;
        }
    }

}

上面的 config 类从 application.yml 中绑定(bind)了以下配置，但需要放在 micronaut 特定配置之前。

application:
    api:
        swagger:
            path: /api-docs/swagger
            version: 3.19.4
            layout: StandaloneLayout
            deepLinking: true
            urls:
            - name: ubw-rest
              url: /api-docs/swagger/ubw-rest-0.1.yml

完成后，将以下 Handlebars / mustache 依赖项添加到 pom

<dependency>
  <groupId>com.github.jknack</groupId>
  <artifactId>handlebars</artifactId>
  <version>4.1.0</version>
  <scope>runtime</scope>
</dependency>

在 resources 文件夹下，创建一个名为 swagger 的文件夹，然后创建一个 index.hbs 文件，其中包含以下内容。

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Swagger-ui</title>

    <link rel="icon" type="image/png" href="https://unpkg.com/swagger-ui-dist@{{version}}/favicon-32x32.png">
    <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@{{version}}/swagger-ui.css">

    <script src="https://unpkg.com/swagger-ui-dist@{{version}}/swagger-ui-standalone-preset.js"></script>
    <script src="https://unpkg.com/swagger-ui-dist@{{version}}/swagger-ui-bundle.js"></script>
</head>
<body>
    <div id="swagger-ui"></div>
    <script>
        window.onload = function() {
            var ui = SwaggerUIBundle({
                urls: [{{#each urls}}
                    {
                        name: "{{name}}",
                        url: "{{url}}"
                    }{{#unless @last}},{{/unless}}{{/each}}
                ],
                dom_id: '#swagger-ui',
                deepLinking: {{deepLinking}},
                presets: [
                    SwaggerUIBundle.presets.apis,
                    SwaggerUIStandalonePreset
                ],
                plugins: [
                    SwaggerUIBundle.plugins.DownloadUrl
                ],
                layout: "{{layout}}"
            });
            window.ui = ui
        }
    </script>
</body>
</html>

最后，在应用程序主类中，添加 @OpenApiDefinition注释以使注释处理器能够扫描整个应用程序。

@OpenAPIDefinition(
        info = @Info(
                title = "swagger-server",
                version = "0.1",
                description = "My API",
                license = @License(name = "Apache 2.0")
        )
)
public class Application {

    public static void main(String[] args) {
        Micronaut.run(Application.class);
    }
}

关于 micronaut 1.0.0 中的注释处理器的一个建议是对象上的公共(public)字段不会被公开，因此如果您想查看输入或返回值的模式，则需要使用 getter/setter。

如果您想尝试上面的运行示例，我有一个带有 swagger 服务器配置的 repo，位于此处 https://github.com/frehov/micronaut-swagger-server其中包括使用要由 Swagger 呈现的 url 和名称对列表发布帖子的能力。