假设应用程序已创建,请将以下内容添加到 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;
}
}
然后添加以下配置类,它绑定下面的属性
@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;
}
}
}
上面的配置类绑定了 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 中注释处理器的一个建议是,对象上的公共字段不会公开,因此如果您想查看输入或返回值的模式,则需要有 getters/setters。
如果您想尝试上面的运行示例,我有一个带有 swagger 服务器配置的存储库,位于此处https://github.com/frehov/micronaut-swagger-server https://github.com/frehov/micronaut-swagger-server其中包括发布带有要由 Swagger 呈现的 url 和名称对列表的帖子。