Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/goodforgod/micronaut-management-openapi

⚙️ Micronaut cloud-friendly OpenAPI/Swagger-UI/Rapidoc management.
https://github.com/goodforgod/micronaut-management-openapi

management micronaut openapi openapi3 rapidoc swagger swagger-ui

Last synced: 19 days ago
JSON representation

⚙️ Micronaut cloud-friendly OpenAPI/Swagger-UI/Rapidoc management.

Host: GitHub
URL: https://github.com/goodforgod/micronaut-management-openapi
Owner: GoodforGod
License: apache-2.0
Created: 2020-09-20T20:02:27.000Z (about 4 years ago)
Default Branch: master
Last Pushed: 2023-08-10T05:56:14.000Z (over 1 year ago)
Last Synced: 2024-10-10T19:22:29.284Z (about 1 month ago)
Topics: management, micronaut, openapi, openapi3, rapidoc, swagger, swagger-ui
Language: Java
Homepage: https://micronaut.io
Size: 267 KB
Stars: 4
Watchers: 3
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# Micronaut Management OpenAPI

[![Minimum required Java version](https://img.shields.io/badge/Java-17%2B-blue?logo=openjdk)](https://openjdk.org/projects/jdk/17/)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.goodforgod/micronaut-management-openapi/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.goodforgod/micronaut-management-openapi)
![Java CI](https://github.com/GoodforGod/micronaut-management-openapi/workflows/CI%20Master/badge.svg)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=GoodforGod_micronaut-management-openapi&metric=alert_status)](https://sonarcloud.io/dashboard?id=GoodforGod_micronaut-management-openapi)
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=GoodforGod_micronaut-management-openapi&metric=coverage)](https://sonarcloud.io/dashboard?id=GoodforGod_micronaut-management-openapi)
[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=GoodforGod_micronaut-management-openapi&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=GoodforGod_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 :rocket:

**Gradle**
```groovy
implementation "io.goodforgod:micronaut-management-openapi:2.0.0"
```

**Maven**
```xml

io.goodforgod
micronaut-management-openapi
2.0.0

```

## Example

Here is [simple Micronaut HTTP application](https://github.com/GoodforGod/micronaut-java-http-template)
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](https://github.com/GoodforGod/micronaut-http-template/blob/master/build.gradle#L40):

```yaml
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](https://micronaut-projects.github.io/micronaut-openapi/latest/guide/index.html).

## Endpoints

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

Endpoints:
- **/openapi** - [OpenAPI](https://spec.openapis.org/oas/v3.1.0) endpoint.
- **/swagger-ui** - [Swagger UI](https://petstore.swagger.io/) endpoint.
- **/rapidoc** - [Rapidoc](https://mrin9.github.io/RapiDoc/examples/example2.html) endpoint.

Swagger UI have **Light\Dark** theme switch!!!

## Configuration

Most of the settings are *cloud-friendly* by default.

```yaml
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:

```yaml
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](LICENSE) file for details.