Micronaut Management OpenAPI

Library provides Micronaut cloud-friendly OpenAPI/Swagger-UI/Rapidoc management endpoints.

Features:

• Cloud-friendly, optimized for file streaming OpenAPI/Swagger-UI/Rapidoc endpoints
• Merging multiple OpenAPI files into one
• OpenAPI exposure endpoint
• Swagger UI exposure endpoint
• Swagger UI Dark\Light theme
• Rapidoc exposure endpoint

Dependency 🚀

Gradle

implementation "io.goodforgod:micronaut-management-openapi:2.0.0"

Maven

<dependency>
    <groupId>io.goodforgod</groupId>
    <artifactId>micronaut-management-openapi</artifactId>
    <version>2.0.0</version>
</dependency>

Example

Here is simple Micronaut HTTP application with configured library and OpenAPI, you play with it.

OpenAPI Generation

Library only exposes OpenAPI, library DOESN'T generate it, this is your responsibility to generate OpenAPI files.

There is Micronaut OpenAPI generator, Gradle config:

dependencies {
    annotationProcessor("io.micronaut.openapi:micronaut-openapi")
    compileOnly("io.swagger.core.v3:swagger-annotations:2.2.15")
}

More info about Micronaut OpenAPI generator in official documentation.

Endpoints

Library automatically scan for OpenAPI files inside JAR in default-directory and expose them via OpenAPI endpoint.

Endpoints:

• /openapi - OpenAPI endpoint.
• /swagger-ui - Swagger UI endpoint.
• /rapidoc - Rapidoc endpoint.

Swagger UI have Light\Dark theme switch!!!

Configuration

Most of the settings are cloud-friendly by default.

openapi:
  path: /openapi                        // Path for OpenAPI endpoint                          (default - /openapi)
  enabled: true                         // Enable OpenAPI exposure                            (default - true)
  merge: false                          // Enable merging OpenAPI found in default-directory  (default - false)
  default-directory: META-INF/swagger   // Path inside JAR where to search OpenAPI            (default - META-INF/swagger)
  exclude:                              // OpenAPI files to exclude from exposure             (path or filename)
    - openapi-1.yml                     // Path or filename (default-directory)
    - META-INF/swagger/openapi-2.yml    // Path or filename (default-directory)
  include:                              // Include ONLY specified OpenAPI files for exposure  (path only)
    - META-INF/swagger/openapi-3.yml    // Path to file inside JAR
    - external-swagger/openapi-4.yml    // Path to file inside JAR
  
  swagger-ui:
    path: /swagger-ui                   // Path for Swagger-UI endpoint                       (default - /swagger-ui)
    enalbed: false                      // Enable Swagger-UI exposure                         (default - false)
  
  rapidoc:
    path: /rapidoc                      // Path for Rapidoc endpoint                          (default - /rapidoc)
    enalbed: false                      // Enable Rapidoc exposure                            (default - false) 

Merge

• merge is disabled then any first OpenAPI file will be exposed (according to exclude and include configuration).
• merge is enabled then all suitable (according to exclude and include configuration) OpenAPI files will be merged into one and exposed.

Security

When you have security enabled and want to provide non-auth access for your OpenAPI/Swagger-UI/Rapodic endpoints here is configuration for such case:

micronaut:
  security:
    intercept-url-map:
      -
        pattern: /openapi|/swagger-ui
        http-method: GET
        access:
          - isAnonymous()

Micronaut Compatability

Starting from version 2.0.0 library ships for Micronaut 4 & Java 17 is required.

Starting from version 1.0.0 library ships for Micronaut 3 & Java 1.8+ is required.

License

This project licensed under the Apache License 2.0 - see the LICENSE file for details.