如何在Micronaut中正确启用Swagger UI？解决文件未生成问题

问题 #

按照Micronaut OpenAPI文档配置后，Swagger UI无法生成，访问/swagger、/swagger-ui时返回404错误，错误响应如下：

{
  "message": "Not Found",
  "_links": {
    "self": {
      "href": "/swagger",
      "templated": false
    }
  },
  "_embedded": {
    "errors": [
      {
        "message": "Page Not Found"
      }
    ]
  }
}

已完成的配置操作：

• 添加依赖：

implementation("io.swagger.core.v3:swagger-annotations")
annotationProcessor("io.micronaut.openapi:micronaut-openapi:4.5.2")

• 在application.yml中配置路由：

micronaut:
  application:
    name: myapp
  router:
    static-resources:
      default:
        enabled: true
      swagger:
        enabled: true
        paths: classpath:META-INF/swagger
        mapping: /swagger/**

• 在根目录创建openapi.properties文件：

swagger-ui.enabled=true
micronaut.openapi.views.spec=apidoc.enabled=true,swagger-ui.enabled=true,swagger-ui.theme=flattop
micronaut.openapi.expand.api.version=v0.1
micronaut.openapi.expand.openapi.description=myapp

• 控制器已添加Operation和ApiResponses注解，但Kotlin项目预期在build/tmp/kapt3/classes/main/META-INF/swagger/下生成的myapp-0.1.yml文件并未生成，需解决Swagger启用问题。

解决步骤 #

1. 修正Kotlin项目的依赖配置 #

Kotlin项目需使用kapt替代annotationProcessor，同时添加Swagger UI的runtime依赖（负责提供UI静态资源）：

implementation("io.swagger.core.v3:swagger-annotations")
kapt("io.micronaut.openapi:micronaut-openapi:4.5.2")
runtimeOnly("io.micronaut.openapi:micronaut-openapi-ui:4.5.2")

2. 调整application.yml的静态资源映射 #

补充Swagger UI的静态资源路由配置，确保UI资源能被正确访问：

micronaut:
  application:
    name: myapp
  router:
    static-resources:
      swagger:
        enabled: true
        paths: classpath:META-INF/swagger
        mapping: /swagger/**
      swagger-ui:
        enabled: true
        paths: classpath:META-INF/swagger/views/swagger-ui
        mapping: /swagger-ui/**

3. 简化openapi.properties配置 #

保留核心配置项，避免冗余设置：

micronaut.openapi.views.spec=swagger-ui.enabled=true
micronaut.openapi.expand.api.version=v0.1
micronaut.openapi.expand.openapi.description=myapp

4. 触发注解处理器生成文档 #

执行清理构建操作，确保注解处理器生成Swagger描述文件：

• 运行命令：./gradlew clean build
• 检查build/tmp/kapt3/classes/main/META-INF/swagger/目录，确认myapp-0.1.yml已生成
• 若仍未生成，需确认控制器类上是否添加了@Tag或@OpenAPIDefinition注解（注解处理器需要此类入口点来生成完整文档）

5. 验证访问路径 #

项目启动后，通过以下路径验证：

• 查看Swagger原始文档：/swagger/myapp-0.1.yml
• 访问Swagger UI界面：/swagger-ui

内容的提问来源于stack exchange，提问作者Rafa Acioly