使用 Maven 为 Micronaut 招摇过市

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 需求添加一个控制器，并用 @Hidden 注释控制器以确保它不会被注释处理器处理。

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

    @Inject
    SwaggerConfig config;

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

然后添加如下配置class，绑定下面的属性

@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;
        }
    }

}

上面的配置class从application.yml绑定了下面的配置，但是需要放在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>

在资源文件夹下，创建一个名为 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>

最后，在应用程序主class中，添加@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 字段不会被公开，所以如果你想，你需要有 getters/setters查看输入或 return 值的架构。

如果您想尝试上面的运行示例，我有一个带有 swagger 服务器配置的回购 https://github.com/frehov/micronaut-swagger-server，其中包括制作 post 以及要由 Swagger 呈现的 url 和名称对的列表。

Answer 2

Micronaut 能够根据这些注释从我们的控制器和方法自动生成 Swagger YAML 定义。添加 swagger-annotations 依赖项 pom.xml.

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>2.0.5</version>
</dependency>

将@OpenAPIDefinition 注释添加到应用程序的主class。

@OpenAPIDefinition(
    info = @Info(
        title = "my app",
        version = "1.0",
        description = "my api",
        contact = @Contact(url = "http://something.com", name = "something", email = "something")
    )
)
public class Application {
    public static void main(String[] args) {
        Micronaut.run(Application.class);
 }
}

Micronaut 在 target/classes/META-INF/swagger/my-app-1.0.yml 生成一个 Swagger 文件。我们可以使用 HTTP 端点在应用程序外部公开它。这是 application.yml 文件中提供的适当配置。

micronaut:
  router:
    static-resources:
      swagger:
        paths: classpath:META-INF/swagger
        mapping: /swagger/**

访问路径http://localhost:8080/swagger/my-app-1.0.yml.

In comparison to Spring Boot, we don't have projects like Swagger SpringFox for Micronaut, so we need to copy the content to an online editor in order to see the graphical representation of our Swagger YAML.

将您的 my-app-1.0.yml 内容粘贴到 https://editor.swagger.io/ 并添加服务器以访问 Swagger UI.

阅读 Micronaut 文档- https://micronaut-projects.github.io/micronaut-openapi/latest/guide/index.html

使用 Maven 为 Micronaut 招摇过市

Swagger for Micronaut with maven

maven

swagger

micronaut