Openapi codegen by gradle plugin: UI not showing correctly

Question

I'm trying to test openapi codegenerator via gradle plugin. So, I have .yml file with documentation (ran it in https://editor.swagger.io/ , looks cool)

openapi: 3.0.2
info:
  title: Testing docs
  version: 1.0.0
tags:
  - name: Registration
paths:
  /registration:
    post:
      tags:
        - Registration
      summary: Register user
...

Here's part of my build.gradle

plugins {
    id "org.openapi.generator" version "5.0.1"
}

def sDir= "$buildDir/generated"
openApiGenerate {
    generatorName = "spring"
    inputSpec = "$rootDir/src/main/resources/documentation/openapi.yml"
    outputDir = "${sDir}"
    apiPackage = "generated.api"
    invokerPackage = "generated.invoker"
    modelPackage = "generated.model"
    configOptions = [
            interfaceOnly: "true",
            useTags: "true"
    ]
}
...

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springdoc:springdoc-openapi-ui:1.5.2'
    implementation 'io.springfox:springfox-swagger2:3.0.0'
    implementation 'org.openapitools:jackson-databind-nullable:0.2.1'
}

I've got bunch of generated interfaces annotated with @Tag and @Api, implemented some of them, but on /swagger-ui.html I do not see tags. Like, I'm getting "not implemented" status, when I run not implemented requests, but I do not see right ui - it looks autogenerated, like when you don't use any of swagger annotations on methods. I can only think that I messed up with some dependencies, but can't really get a clue.

Answer 1

The ui you see is not generated from the documentation .yml file you use to generate your code. Instead, the ui is generated from the generated code, which has it's own annotations that currently are springfox annotations, which are swagger2 annotations instead of openapi 3 annotations (although your original file is openapi 3).

Generated openapi 3 annotations support is coming soon, but in any case, in short, you should have to complete missing annotations and necessary beans yourself, but this way makes it very hard to match the resulting openapi definition to your original documentation file.

Luckily there's a better alternative: Just add your yml file in src/main/resources/static and add this line to your application.properties file:

springdoc.swagger-ui.url=/<your_file>.yml

As stated here https://springdoc.org/#how-can-use-custom-jsonyml-file-instead-of-generated-one. You already have springdoc-ui dependency so you don't need to add any more dependencies.

This will ignore your code annotations and generate the ui directly from your documentation .yml file