当使用 openapi 生成器 cli jar 生成 Springboot 项目时，SwaggerUI 默认为版本 2

Question

我正在尝试使用以下带有 openapi 生成器 cli jar 的 yaml 文件生成一个 spring 引导项目

openapi: 3.0.0
info:
  title: Dealer Management System
  description: REST APIs to manage dealers
  version: 1.0.0
  contact:
    name: Srinivasan Ramu
    email: srinimarva@gmail.com
tags:
  - name: User
    description: REST API for creating admin user and login
servers:
  - url: https://dealerengine-test.com/v1
    description: Test server
  - url: https://dealerengine-stage.com/v1
    description: Stage server
paths:
  /user/createAdminUser:
    post:
      summary: Create Admin User
      description: To create an admin user
      operationId: addAdminUser
      tags:
        - User
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/user'
      responses:
        '200':
          description: Admin user created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
        '400':
          description: Error in creating admin user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Example:
                  $ref: '#/components/examples/errorcreatingadminuser'
        '404':
          description: Resource not found for creating admin user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Example:
                  $ref: '#/components/examples/resourcenotfoundforcreatingadminuser'
  /user/adminUserLogin:
    post:
      summary: Admin User Login
      description: To login as an admin user
      operationId: adminUserLogin
      tags:
        - User
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/loginRequest'
            example:
              username: marva27
              password: Boeing@27
      responses:
        '200':
          description: Admin user login success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/message'
              example:
                description: login success
        '400':
          description: Error in Admin User Login
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Example:
                  $ref: '#/components/examples/errorinadminuserlogin'
        '404':
          description: Admin User Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                Example:
                  $ref: '#/components/examples/adminusernotfound'
components:
  examples:
    errorcreatingadminuser:
      value:
        id: bad_request
        message: user name is required
    resourcenotfoundforcreatingadminuser:
      value:
        id: not_found
        message: resource not found for creating admin user
    errorinadminuserlogin:
      value:
        id: bad_request
        message: password is incorrect
    adminusernotfound:
      value:
        id: not_found
        message: admin user not found
  schemas:
    error:
      type: object
      properties:
        id:
          type: string
          description: Unique id of an error
        message:
          type: string
          description: Meaningful message about the error
      required:
        - id
        - message
    loginRequest:
      type: object
      properties:
        username:
          type: string
          description: Name of the user
        password:
          type: string
          description: Password of the user
      required:
        - username
        - password
    message:
      type: object
      properties:
        description:
          type: string
          description: Meaningful message about successful completion of an operation
    user:
      type: object
      properties:
        firstName:
          type: string
          description: First name of the user
          example: Srinivasan
        lastName:
          type: string
          description: Last name of the user
          example: Ramu
        emailAddress:
          type: string
          description: Email address of the user
          example: srinimarva@gmail.com
        userName:
          type: string
          description: User name
          example: marva27
        password:
          type: string
          description: Password of the user
          example: ******@27

当我使用以下配置和命令生成 Springboot 项目时，我看到我的 swagger-ui 默认为 Swagger 2，并且我为错误对象记录的示例未显示。如何将我的 swagger-ui 默认为版本 3？

{
    "basePackage":"com.user.www",
    "configPackage":"com.user.www.config",
    "apiPackage":"com.user.www.api",
    "modelPackage":"com.user.www.model",
    "groupId":"com.user.www",
    "artifactId":"user-engine"
}

当我在 https://editor.swagger.io/ 中查看 yaml 内容时，我在 swagger-ui 中看到了预期的示例

Answer 1

我猜你没有正确地 C&P。

我刚刚用你的文件设置了一个测试项目并使用了 openapi-generator-cli.jar 使用命令：

java -jar openapi-generator-cli.jar generate -i stack.yml -g spring -p java8=true

我创建了项目，但出现错误 class：

package org.openapitools.model;
import java.util.Objects;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.annotation.JsonCreator;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import org.openapitools.jackson.nullable.JsonNullable;
import javax.validation.Valid;
import javax.validation.constraints.*;

/**
 * Error
 */
@javax.annotation.Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2022-04-05T08:34:53.094779300+02:00[Europe/Berlin]")
public class Error   {
  @JsonProperty("id")
  private String id;

  @JsonProperty("message")
  private String message;

  public Error id(String id) {
    this.id = id;
    return this;
  }

  /**
   * Unique id to represent a type of error
   * @return id
  */
  @ApiModelProperty(example = "bad_request", value = "Unique id to represent a type of error")


  public String getId() {
    return id;
  }

  public void setId(String id) {
    this.id = id;
  }

  public Error message(String message) {
    this.message = message;
    return this;
  }

  /**
   * Meaningful message about what went wrong
   * @return message
  */
  @ApiModelProperty(example = "dealer id already exists", value = "Meaningful message about what went wrong")


  public String getMessage() {
    return message;
  }

  public void setMessage(String message) {
    this.message = message;
  }


  @Override
  public boolean equals(java.lang.Object o) {
    if (this == o) {
      return true;
    }
    if (o == null || getClass() != o.getClass()) {
      return false;
    }
    Error error = (Error) o;
    return Objects.equals(this.id, error.id) &&
        Objects.equals(this.message, error.message);
  }

  @Override
  public int hashCode() {
    return Objects.hash(id, message);
  }

  @Override
  public String toString() {
    StringBuilder sb = new StringBuilder();
    sb.append("class Error {\n");
    
    sb.append("    id: ").append(toIndentedString(id)).append("\n");
    sb.append("    message: ").append(toIndentedString(message)).append("\n");
    sb.append("}");
    return sb.toString();
  }

  /**
   * Convert the given object to string with each line indented by 4 spaces
   * (except the first line).
   */
  private String toIndentedString(java.lang.Object o) {
    if (o == null) {
      return "null";
    }
    return o.toString().replace("\n", "\n    ");
  }
}

此外，我能够启动并接收模式：