SwaggerUI未能正确显示由OpenApi代码生成器生成的文档化API。

huangapple 未分类评论51阅读模式
英文:

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 屏幕截图如下:

SwaggerUI未能正确显示由OpenApi代码生成器生成的文档化API。

英文:

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:

&lt;plugin&gt;
  &lt;groupId&gt;org.openapitools&lt;/groupId&gt;
  &lt;artifactId&gt;openapi-generator-maven-plugin&lt;/artifactId&gt;
  &lt;version&gt;4.1.1&lt;/version&gt;
  &lt;configuration&gt;
    &lt;generatorName&gt;spring&lt;/generatorName&gt;
    &lt;inputSpec&gt;${project.basedir}/src/main/resources/exampleApi.yaml&lt;/inputSpec&gt;
    &lt;apiPackage&gt;com.example.openapi.generated.api&lt;/apiPackage&gt;
    &lt;modelPackage&gt;com.example.openapi.generated.models&lt;/modelPackage&gt;
    &lt;generateSupportingFiles&gt;false&lt;/generateSupportingFiles&gt;
    &lt;output&gt;${project.basedir}&lt;/output&gt;
    &lt;configOptions&gt;
      &lt;dateLibrary&gt;java8&lt;/dateLibrary&gt;
      &lt;java8&gt;true&lt;/java8&gt;
      &lt;interfaceOnly&gt;true&lt;/interfaceOnly&gt;
    &lt;/configOptions&gt;
  &lt;/configuration&gt;
&lt;/plugin&gt;

This plugin works well and I get interface like this

@Api(value = &quot;example&quot;, description = &quot;the example API&quot;)
public interface ExampleApi {

    default Optional&lt;NativeWebRequest&gt; getRequest() {
        return Optional.empty();
    }

    @ApiOperation(value = &quot;Example GET request&quot;, nickname = &quot;exampleGetRequest&quot;, notes = &quot;Send example GET request&quot;, tags = {&quot;example&quot;,})
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = &quot;Successful operation&quot;),
            @ApiResponse(code = 400, message = &quot;Example Bad Request&quot;),
            @ApiResponse(code = 404, message = &quot;Example Not Found&quot;)})
    @RequestMapping(value = &quot;/example&quot;, method = RequestMethod.GET)
    default ResponseEntity&lt;Void&gt; exampleGetRequest() {
        return new ResponseEntity&lt;&gt;(HttpStatus.NOT_IMPLEMENTED);
    }
}

I'm implementing my interface with this class:

@RestController
public class ExampleApiImpl implements ExampleApi {

    @Override
    public ResponseEntity&lt;Void&gt; 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?

SwaggerUI screen
SwaggerUI未能正确显示由OpenApi代码生成器生成的文档化API。

答案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.

huangapple
  • 本文由 发表于 2020年4月7日 23:52:05
  • 转载请务必保留本文链接:https://java.coder-hub.com/61084108.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定