用maven为Micronaut大摇大摆

Question

我想从spring boot 2中切换到Micronaut框架。而我也在为那些大摇大摆的场景而挣扎。

在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>

和swaggreconfig.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

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注释添加到应用程序的主类中。

@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。

与spring boot相比，我们没有像Swagger SpringFox for Micronaut这样的项目，所以我们需要将内容复制到一个在线编辑器，以便看到我们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

Answer 2

假设应用程序已经创建，在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中添加以下注释ProcessorPaths

<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需要的控制器，并使用@hiddit对该控制器进行注释，以确保它不会被注释处理器处理。

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

    @Inject
    SwaggerConfig config;

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

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

@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绑定了以下配置，但需要放在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

完成后，向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>

最后，在application main类中，添加@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);
    }
}

关于Micronaut1.0.0中的注释处理器的一个建议是，对象上的公共字段不会公开，因此如果您想要查看输入或返回值的模式，就需要有getter/setter。

如果您想尝试上面的一个运行示例，我有一个带有swagger服务器配置的repo，该配置位于https://github.com/frehov/micronaut-swagger-server中，它包含了一个由swagger呈现的url和名称对列表的功能。