英文:
SwaggerUI doesn't show documented API properly generated by OpenApi codegen
问题
我正在使用 openapi-generator-maven-plugin 从 YAML 文档生成代码。
openapi: 3.0.3
info:
title: 示例 API 文档
description: 这些是示例端点。
termsOfService: https://localhost:8080/termsOfService
license:
name: 无许可证
url: https://localhost:8080/license
version: 1.0-SNAPSHOT
servers:
- url: https://localhost:8080/
- url: http://localhost:8080/
tags:
- name: 示例
description: 示例标签
paths:
/example:
get:
tags:
- 示例
summary: 示例 GET 请求
description: 发送示例 GET 请求
operationId: exampleGetRequest
responses:
200:
description: 操作成功
content: {}
400:
description: 示例错误请求
content: {}
404:
description: 示例未找到
content: {}
这是我如何配置 Maven 插件来生成接口的方法:
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>4.1.1</version>
<configuration>
<generatorName>spring</generatorName>
<inputSpec>${project.basedir}/src/main/resources/exampleApi.yaml</inputSpec>
<apiPackage>com.example.openapi.generated.api</apiPackage>
<modelPackage>com.example.openapi.generated.models</modelPackage>
<generateSupportingFiles>false</generateSupportingFiles>
<output>${project.basedir}</output>
<configOptions>
<dateLibrary>java8</dateLibrary>
<java8>true</java8>
<interfaceOnly>true</interfaceOnly>
</configOptions>
</configuration>
</plugin>
这个插件工作得很好,我得到了类似以下的接口:
@Api(value = "example", description = "示例 API")
public interface ExampleApi {
default Optional<NativeWebRequest> getRequest() {
return Optional.empty();
}
@ApiOperation(value = "示例 GET 请求", nickname = "exampleGetRequest", notes = "发送示例 GET 请求", tags = {"示例",})
@ApiResponses(value = {
@ApiResponse(code = 200, message = "操作成功"),
@ApiResponse(code = 400, message = "示例错误请求"),
@ApiResponse(code = 404, message = "示例未找到")})
@RequestMapping(value = "/example", method = RequestMethod.GET)
default ResponseEntity<Void> exampleGetRequest() {
return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
}
}
我正在使用以下类实现我的接口:
@RestController
public class ExampleApiImpl implements ExampleApi {
@Override
public ResponseEntity<Void> exampleGetRequest() {
return ResponseEntity.ok().build();
}
}
我已经检查了解决方案,当我进行 API 调用时,我得到了 HTTP 状态 200,但是当我尝试访问 Swagger UI 页面时,这个 API 端点没有被记录。有没有办法配置 OpenAPI UI 或 SwaggerUI 以指向我的 YAML 文档?
SwaggerUI 屏幕截图如下:
英文:
I'm using openapi-generator-maven-plugin to generate code from YAML documentation.
openapi: 3.0.3
info:
title: Example API Doc
description: Those are example endpoints.
termsOfService: https://localhost:8080/termsOfService
license:
name: No license
url: https://localhost:8080/license
version: 1.0-SNAPSHOT
servers:
- url: https://localhost:8080/
- url: http://localhost:8080/
tags:
- name: example
description: Example Tag
paths:
/example:
get:
tags:
- example
summary: Example GET request
description: Send example GET request
operationId: exampleGetRequest
responses:
200:
description: Successful operation
content: {}
400:
description: Example Bad Request
content: {}
404:
description: Example Not Found
content: {}
This is how I configure maven plugin to generate interfaces:
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>4.1.1</version>
<configuration>
<generatorName>spring</generatorName>
<inputSpec>${project.basedir}/src/main/resources/exampleApi.yaml</inputSpec>
<apiPackage>com.example.openapi.generated.api</apiPackage>
<modelPackage>com.example.openapi.generated.models</modelPackage>
<generateSupportingFiles>false</generateSupportingFiles>
<output>${project.basedir}</output>
<configOptions>
<dateLibrary>java8</dateLibrary>
<java8>true</java8>
<interfaceOnly>true</interfaceOnly>
</configOptions>
</configuration>
</plugin>
This plugin works well and I get interface like this
@Api(value = "example", description = "the example API")
public interface ExampleApi {
default Optional<NativeWebRequest> getRequest() {
return Optional.empty();
}
@ApiOperation(value = "Example GET request", nickname = "exampleGetRequest", notes = "Send example GET request", tags = {"example",})
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Successful operation"),
@ApiResponse(code = 400, message = "Example Bad Request"),
@ApiResponse(code = 404, message = "Example Not Found")})
@RequestMapping(value = "/example", method = RequestMethod.GET)
default ResponseEntity<Void> exampleGetRequest() {
return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
}
}
I'm implementing my interface with this class:
@RestController
public class ExampleApiImpl implements ExampleApi {
@Override
public ResponseEntity<Void> exampleGetRequest() {
return ResponseEntity.ok().build();
}
}
I've checked the solution and I've got HTTP status 200 when I perform api call, but when I try to access swagger-ui page, this API endpoint is not documented. Is there any way to configure OpenAPI UI or SwaggerUI to point to my yaml documentation?
答案1
得分: 0
如果它仍然是当前热门话题。
看起来您在使用 OpenAPI UI 来进行 Swagger 3 注释,但是 OpenApi 生成器只能创建 Swagger 2 注释:https://stackoverflow.com/questions/62915594/open-api-code-generator-maven-plugin-uses-old-swagger-2-annotations-instead-of-s
解决方案#1 - 使用 Swagger v2 UI。删除 openApi 依赖,改用 io.springfox:springfox-swagger2:{version}
用于 UI 页面。
解决方案#2 - 覆盖生成 v3 注释的 Mustache 模板。
英文:
if it's still topical.
Looks like you use OpenAPI UI for Swagger 3 annotations, but OpenApi generator can create only Swagger 2 annotations: https://stackoverflow.com/questions/62915594/open-api-code-generator-maven-plugin-uses-old-swagger-2-annotations-instead-of-s
Solution #1 - use Swagger v2 UI. Remove openApi dependency and use io.springfox:springfox-swagger2:{version}
for UI page.
Solution #2 - override mustache templates for generation v3 annotations.
专注分享java语言的经验与见解,让所有开发者获益!
评论