Предполагая, что приложение уже создано, добавьте следующее 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
и добавьте следующее к вамannotationProcessorPaths в плагине maven-compiler-plugin
<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;
}
}
}
.Приведенный выше класс config связывает следующую конфигурацию из application.yml, но его необходимо поместить до конкретной конфигурации микронавта.
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>
Наконец, в главном классе приложения добавьте @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, которая включает в себя возможность сделать пост со спискомпары URL и имен для рендеринга Swagger.