OpenAPI Spec for Spring

This library builds an OpenAPI 3 spec at runtime for a Spring Boot application. It reads the Spring WebMVC handler methods and their Swagger annotations.

Each part of the build is a Spring bean that Spring Boot auto-configures with @ConditionalOnMissingBean. To change a part, define your own bean of the same type. The interfaces you can implement, such as filters and customizers, are in the api module.

The library does not depend on the swagger-core or swagger-models modules.

Origin

This project is a hard fork of qaware/openapi-generator-for-spring, written by QAware GmbH. Thanks to QAware for the original work. meshcloud GmbH maintains this fork under the Apache License 2.0, see LICENSE.txt and NOTICE.

Getting started

The artifacts are in the GitHub Packages Maven repository https://maven.pkg.github.com/meshcloud/openapi-spec-for-spring. GitHub Packages needs a GitHub token with the read:packages scope, also for public packages.

repositories {
  maven {
    url = 'https://maven.pkg.github.com/meshcloud/openapi-spec-for-spring'
    credentials {
      username = providers.gradleProperty('gpr.user').orNull
      password = providers.gradleProperty('gpr.token').orNull
    }
  }
}

dependencies {
  implementation('io.meshcloud.openapispecforspring:openapi-spec-for-spring-boot3-starter:1.0.0')
}

Put gpr.user and gpr.token in ~/.gradle/gradle.properties.

When the application runs, it serves the spec at /v3/api-docs as JSON. It also serves YAML to requests that accept YAML when the application has com.fasterxml.jackson.dataformat:jackson-dataformat-yaml on its classpath. See the WebMVC demo.

Spring HATEOAS

When the application has Spring HATEOAS on its classpath, the spec describes every RepresentationModel in the HAL format:

• A RepresentationModel subclass gets _links in place of links.
• EntityModel<T> is allOf the schema of T and an object with _links.
• CollectionModel<T> has _embedded with the content under its collection relation, and _links. The relation comes from the application's LinkRelationProvider, so @Relation applies.
• PagedModel<T> also has page.
• _links and page are readOnly and not required, because Spring HATEOAS leaves out empty links and a PagedModel can have no page metadata.

The spec does not check the media type of the response, so a RepresentationModel that the application also serves as plain JSON still gets the HAL schema. Set openapi-spec-for-spring.hateoas.enabled=false to turn the HAL schemas off.

Branches and versions

Each Spring Boot major version has its own branch, for example spring-boot-3.x. The Spring Boot major is part of the artifactId, for example openapi-spec-for-spring-boot3-starter.

A release is a tag <branch>-v<semver> on that branch, for example spring-boot-3.x-v1.0.0. The artifact version is the semver part, here 1.0.0.

Each push to spring-boot-3.x also publishes the version spring-boot-3.x-SNAPSHOT, and each pull request from a branch of this repository publishes spring-boot-3.x-PR-<number>-SNAPSHOT, which is deleted when the pull request closes. To try a change before its release, depend on such a version, for example io.meshcloud.openapispecforspring:openapi-spec-for-spring-boot3-starter:spring-boot-3.x-SNAPSHOT.

Configuration properties

All properties have the prefix openapi-spec-for-spring:

• OpenApiConfigurationProperties
• OpenApiInfoConfigurationProperties
• OpenApiHateoasConfigurationProperties
• OpenApiDataConfigurationProperties
• Java8TimeTypeResolverConfigurationProperties

Build

The build needs Nix with flakes:

nix develop --command ./gradlew build

The coverage report of all modules is in openapi-spec-for-spring-test/build/reports/jacoco/testCodeCoverageReport/.