Assuming the application is already created, add the following to you pom.xml
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>${swagger.version}</version>
<scope>compile</scope>
</dependency>
where the property swagger.version is set to 2.0.3
add the following to you annotationProcessorPaths in the maven-compiler-plugin
<path>
<groupId>io.micronaut.configuration</groupId>
<artifactId>micronaut-openapi</artifactId>
<version>${micronaut.version}</version>
</path>
Then add the following to your micronaut router section.
micronaut:
router:
static-resources:
swagger:
paths: classpath:META-INF/swagger
mapping: ${application.api.swagger.path}/**
This will expose your swagger/oas yml file that is generated during compile, provided you use the configuration below. You can of course change the ${application.api.swagger.path}
to just be /api-docs/swagger
or something to your liking.
As described in the docs, you can also do the following --features=swagger-java
to add the above dependecies when you initially create the project.
If you want to render the api-specification from the application itself, then you need to add some more code. The following example is probably more fleshed out than it needs to be, but for my purpose the application serves as a central renderer for swagger/oas specifications.
First add a controller for you swagger needs, and annotate the controller with @Hidden
to make sure it doesn't get processed by the annotation processor.
@Hidden
@Controller("/api")
public class SwaggerController {
@Inject
SwaggerConfig config;
@View("swagger/index")
@Get
public SwaggerConfig index() {
return config;
}
}
Then add the following configuration class, which binds the properties from below
@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;
}
}
}
The above config class binds the following configuration from application.yml, but needs to be placed before the micronaut specific configuration.
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
When that is done, add the following handlebars/mustache dependency to the pom
<dependency>
<groupId>com.github.jknack</groupId>
<artifactId>handlebars</artifactId>
<version>4.1.0</version>
<scope>runtime</scope>
</dependency>
Under the resources folder, create a folder named swagger, and then create an index.hbs file containing the following.
<!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>
Finally, in the application main class, add the @OpenApiDefinition
annotation to enable the annotation processor to scan the entire appliaction.
@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);
}
}
A word of advice regarding the annotation processor as it stands in micronaut 1.0.0 is that public fields on an object will not be exposed, so you need to have getters/setters if you want to see the schema for the input or return values.
If you'd like to try out a running example of the above, I have a repo with the swagger server configuration located here https://github.com/frehov/micronaut-swagger-server which includes the ability to make a post with a list of url and name pairs to be rendered by Swagger.