假设已经创建了应用程序，请将以下内容添加到 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 规范的中央渲染器。
首先为您的招摇需要添加一个控制器，并注释控制器@Hidden以确保它不会被注释处理器处理。
@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>
最后，在应用程序主类中，添加@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 中的注释处理器的一个建议是对象上的公共字段不会被公开，因此如果您想查看输入或返回值的模式，您需要拥有 getter/setter。
如果您想尝试上面的运行示例，我有一个带有 swagger 服务器配置的 repo，位于https://github.com/frehov/micronaut-swagger-server，其中包括发布帖子的功能要由 Swagger 呈现的 url 和名称对列表。