Why can i not generate spring api docs with Spring Boot 3 and OpenAPI spec?

Question

So this issue has been discussed several times, but none of the fixes suggested in these work for me:

Spring Boot 3 springdoc-openapi-ui doesn't work

Spring Boot 3.0.0 and Springdoc incompatible?

I have a Kotlin Spring Boot 3.2.3 project with an OpenAPI code generation from a yaml specification. The generation of code works fine with the openApiGenerate gradle task in the output generated folder, but neither static swagger html docs appear nor can i access anything via the default /v3/api-docs route.

I already use the springdoc-openapi-starter-webmvc-ui dependency with a 2.x version to be "compatible" with Spring Boot 3 as seen in my build.gradle setup:

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
    id 'org.springframework.boot' version '3.2.3'
    id 'io.spring.dependency-management' version '1.1.4'
    id 'org.jetbrains.kotlin.jvm' version '1.9.22'
    id 'org.jetbrains.kotlin.plugin.spring' version '1.9.22'
    id 'org.jetbrains.kotlin.plugin.jpa' version '1.9.22'
    id "org.openapi.generator" version "7.3.0"
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    sourceCompatibility = '21'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-mustache'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'com.fasterxml.jackson.module:jackson-module-kotlin'
    implementation 'org.jetbrains.kotlin:kotlin-reflect'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    runtimeOnly 'com.h2database:h2'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    implementation "org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0" // Also doesnt work with another version like 2.0.0
}

tasks.withType(KotlinCompile) {
    kotlinOptions {
        freeCompilerArgs += '-Xjsr305=strict'
        jvmTarget = '21'
    }
}

tasks.named('test') {
    useJUnitPlatform()
}

openApiGenerate {
    generatorName.set("kotlin-spring")
    inputSpec.set("${project.rootDir}/openapi.yaml")
    outputDir.set("${project.buildDir}/generated")
    apiPackage.set("com.example.api")
    modelPackage.set("com.example.model")
    configOptions.put("library", "spring-boot")
    configOptions.put("language", "kotlin")
}

I also added the @OpenApiDefinition annotation to my main class:

package com.example.kotlinrest

import io.swagger.v3.oas.annotations.OpenAPIDefinition
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.context.annotation.ComponentScan

@SpringBootApplication
@ComponentScan(basePackages = ["com.example.kotlinrest.api", "com.example.kotlinrest.model"])
@OpenAPIDefinition
class KotlinRestApplication

fun main(args: Array<String>) {
    runApplication<KotlinRestApplication>(*args)
}

Since generation of the code (controller stubs and models etc.) from my OpenAPI specification works fine, it doesn't seem to be related to that setup. Why are no docs generated?

Answer 1

Spring boot 3 with springfox is currently incompatible but Open API 3 is very much compatible and does generate /v3/api-docs

My Spring Boot App class has

@OpenAPIDefinition(servers = {@Server(url = "/user-service", description = "User service description")})

And pom.xml

    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.3.0</version>
    </dependency>

Hope this will help you.