Question

我有以下规范employee.yaml文件：

openapi: 3.0.2
info:
  title: Employee api
  version: 0.0.0
  description: Employee api specification
  contact:
    name: Lorem Ipsum
    email: lorem@ipsum.com

tags:
  - name: "Employee"
  - name: "EmployeeDisability"

paths:
  /employees:
    $ref: 'paths/employees.yaml'

在 /paths/employees.yaml

/employees:
    get:
      summary: This is summary
      tags:
        - 'Employee'
      description: This is description
      operationId: getEmployees
      responses:
        "200":
          description: The request has succeeded - OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '../dtos/employee.yaml'

当我从 /paths/employees.yaml 复制代码并将其粘贴到 employee.yaml 路径时，一切都会正确生成。我不认为这是文件 employees.yaml 的路径问题。有没有人遇到过类似的问题？

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>employees-service-spec</artifactId>
    <packaging>jar</packaging>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <java.version>11</java.version>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <swagger-annotations-version>1.5.22</swagger-annotations-version>
        <jersey-version>2.27</jersey-version>
        <jackson-version>2.10.2</jackson-version>
        <jodatime-version>2.7</jodatime-version>
        <maven-plugin-version>1.0.0</maven-plugin-version>
        <junit-version>4.8.1</junit-version>
        <springfox-version>2.9.2</springfox-version>
        <threetenbp-version>1.3.8</threetenbp-version>
        <datatype-threetenbp-version>2.6.4</datatype-threetenbp-version>
        <spring-boot-starter-test-version>2.1.1.RELEASE</spring-boot-starter-test-version>
        <spring-boot-starter-web-version>2.1.0.RELEASE</spring-boot-starter-web-version>
        <junit-version>4.12</junit-version>
        <migbase64-version>2.2</migbase64-version>
        <jackson-databind-nullable>0.2.1</jackson-databind-nullable>
    </properties>

    <dependencies>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>${swagger-annotations-version}</version>
        </dependency>
        <dependency>
            <groupId>org.glassfish.jersey.core</groupId>
            <artifactId>jersey-client</artifactId>
            <version>${jersey-version}</version>
        </dependency>
        <dependency>
            <groupId>org.glassfish.jersey.media</groupId>
            <artifactId>jersey-media-multipart</artifactId>
            <version>${jersey-version}</version>
        </dependency>
        <dependency>
            <groupId>org.glassfish.jersey.media</groupId>
            <artifactId>jersey-media-json-jackson</artifactId>
            <version>${jersey-version}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.jaxrs</groupId>
            <artifactId>jackson-jaxrs-base</artifactId>
            <version>${jackson-version}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>${jackson-version}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-annotations</artifactId>
            <version>${jackson-version}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>${jackson-version}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.jaxrs</groupId>
            <artifactId>jackson-jaxrs-json-provider</artifactId>
            <version>${jackson-version}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.datatype</groupId>
            <artifactId>jackson-datatype-joda</artifactId>
            <version>${jackson-version}</version>
        </dependency>
        <dependency>
            <groupId>joda-time</groupId>
            <artifactId>joda-time</artifactId>
            <version>${jodatime-version}</version>
        </dependency>
        <dependency>
            <groupId>com.brsanthu</groupId>
            <artifactId>migbase64</artifactId>
            <version>${migbase64-version}</version>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>${junit-version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <version>${spring-boot-starter-test-version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>${spring-boot-starter-web-version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox-version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox-version}</version>
        </dependency>
        <dependency>
            <groupId>org.threeten</groupId>
            <artifactId>threetenbp</artifactId>
            <version>${threetenbp-version}</version>
        </dependency>
        <dependency>
            <groupId>com.github.joschi.jackson</groupId>
            <artifactId>jackson-datatype-threetenbp</artifactId>
            <version>${datatype-threetenbp-version}</version>
        </dependency>
        <dependency>
            <groupId>org.openapitools</groupId>
            <artifactId>jackson-databind-nullable</artifactId>
            <version>${jackson-databind-nullable}</version>
        </dependency>


        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-openfeign</artifactId>
            <version>3.0.2</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.openapitools</groupId>
                <artifactId>openapi-generator-maven-plugin</artifactId>
                <version>5.1.0</version>
                <executions>
                    <execution>
                        <id>generate-java</id>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                        <configuration>
                            <configOptions>
                                <apiPackage>com.example.demotest.api1</apiPackage>
                                <dateLibrary>java8</dateLibrary>
                                <examples>false</examples>
                                <implicitHeaders>false</implicitHeaders>
                                <interfaceOnly>false</interfaceOnly>
                                <library>spring-cloud</library>
                                <modelPackage>com.example.demotest.model1</modelPackage>
                                <returnSuccessCode>true</returnSuccessCode>
                                <swaggerDocketConfig>true</swaggerDocketConfig>
                                <unhandledException>true</unhandledException>
                                <useOptional>false</useOptional>
                                <useTags>true</useTags>
                            </configOptions>
                            <generatorName>spring</generatorName>
                            <typeMappings>
                                <typeMapping>OffsetDateTime=Instant</typeMapping>
                            </typeMappings>
                            <importMappings>Problem=org.zalando.problem.Problem,java.time.OffsetDateTime=java.time.Instant</importMappings>
                            <inputSpec>${project.basedir}/src/main/resources/employees-service-spec/employee/employee.yaml</inputSpec>
                            <modelNameSuffix>DTO</modelNameSuffix>
                            <skipValidateSpec>true</skipValidateSpec>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

        </plugins>
    </build>
</project>

也许还有其他我没有发现的限制？

Answer 1

我发现了问题的原因，在文件 /paths/employees.yaml 中不应该有路径，而且模型的路径不正确：

/employees: <-- remove this
get:
  summary: This is summary
  tags:
    - 'Employee'
  description: This is description
  operationId: getEmployees
  responses:
    "200":
      description: The request has succeeded - OK
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '../dtos/employee.yaml'  <-- here path sould be: '../dtos/employee.yaml#/Employee'

当员工模型是：

Employee:
  description: Employee
  type: object
  properties:
    number:
      description: The number of employee
      type: string
    unemployedStatus:
      description: The unemployed status of employee
      type: boolean

Open Api 3 生成器不会为 $ref 引用的路径生成类

1 个答案: