基於openapi3.0的yaml文件生成java代碼的一次實踐

在github上看了swagger-api項目（https://github.com/swagger-api/swagger-codegen）中的一些文檔以及swagger-codegen的使用說明，還是覺得有些麻煩，該項目中有提到使用swagger-codegen-maven-plugin但是看了下給的樣例，swagger的yaml文件還是用的幾年前更新的老的樣例，而使用openapi3.0規範的yaml文件無法進行代碼生成。在maven中央倉庫中找到這樣一個插件：openapi-generator-maven-plugin，在項目中使用形式如下：

• Pom依賴：

<build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <!-- Plugin that provides API-first development using openapi-generator
                    to generate Spring-MVC endpoint stubs at compile time from an OpenAPI definition
                    file -->
                <groupId>org.openapitools</groupId>
                <artifactId>openapi-generator-maven-plugin</artifactId>
                <version>3.3.1</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                        <configuration>
                            <inputSpec>${project.basedir}/src/swagger/馬上開課openapi3.0文檔.yaml</inputSpec>
                            <generatorName>spring</generatorName>
                            <apiPackage>com.example.openapigenerator.rest</apiPackage>
                            <modelPackage>com.example.openapigenerator.rest.dto</modelPackage>
                            <output>${project.basedir}</output>
                            <supportingFilesToGenerate>ApiUtil.java</supportingFilesToGenerate>
                            <configOptions>
                                <delegatePattern>true</delegatePattern>
                            </configOptions>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

將yaml文件放置在inputSpec指定的位置；生成的文件出現在output+apiPackage指定的位置；生成的model文件出現在output+modelPackage指定的位置。

• 測試使用的yaml文件:

openapi: 3.0.0
info:
  title: [xxxx]API文檔
  description: [xxxx]功能模塊及接口設計文檔
  version: '0.1'
  termsOfService: 'http://swagger.io/terms/'
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
servers:
  - url: '{protocol}://[xxxx].xmkp/v1'
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
    description: Main (production) server
  - url: 'dev.[xxxx].com:8080/api/v1'
    description: Development server
  - url: 'http://test.[xxxx].xmkp/v1'
    description: Test server
tags:
  - name: Courses
    description: 專輯課程管理
paths:
  /courses:
    post:
      tags:
        - Courses
      summary: 創建專輯課程
      description: 需要在主站創建專輯，此時狀態爲【編輯中】
      operationId: createCourse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCourseRequest'
      responses:
        '200':
          description: 操作成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCourseRequest'
        '404':
          description: 服務未找到
          content:
            application/json:
              schema:
                type: string
                default: 服務未找到
  /courses/{courseId}:
    get:
      tags:
        - Courses
      summary: 根據 課程id獲取課程詳情
      description: 若已經同步到主站，詳情包括同步補充信息
      operationId: getCourseDetail
      parameters:
        - in: path
          name: courseId
          description: 本地專輯課程id
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: 操作成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CourseDto'
        '404':
          description: 資源未找到
          content:
            application/json:
              schema:
                type: string
                default: 資源 未找到
components:
  schemas:
    CreateCourseRequest:
      description: 創建課程時請求對象
      type: object
      properties:
        status:
          enum:
            - underReview
            - published
            - inactive
            - editing
            - rejected
            - removed
          description: '課程狀態[審覈中，已發佈，已下架，編輯中，未通過，被下架]'
        price:
          type: number
          format: 浮動
        title:
          type: string
        cover:
          type: string
        presenterRef:
          type: integer
          format: int64
        shortDesc:
          type: string
        albumRef:
          type: integer
          format: int64
          description: 主站專輯id引用
        homepageRef:
          type: integer
          format: int64
          description: 個人主頁id引用
        poster:
          type: string
          description: 海報

    CourseDto:
      description: 展示詳情時課程對象
      type: object
      properties:
        id:
          type: integer
          format: int64
        status:
          enum:
            - underReview
            - published
            - inactive
            - editing
            - rejected
            - removed
          description: '課程狀態[審覈中，已發佈，已下架，編輯中，未通過，被下架]'
        price:
          type: number
          format: 浮動
        title:
          type: string
        cover:
          type: string
        presenterRef:
          type: integer
          format: int64
        shortDesc:
          type: string
        albumRef:
          type: integer
          format: int64
          description: 主站專輯id引用
        homepageRef:
          type: integer
          format: int64
          description: 個人主頁id引用
        poster:
          type: string
          description: 海報
        createdTime:
          type: string
          format: date
    CourseListDto:
      description: 課程列表中課程對象
      type: object
      properties:
        status:
          enum:
            - underReview
            - published
            - inactive
            - editing
            - rejected
            - removed
          description: '課程狀態[審覈中，已發佈，已下架，編輯中，未通過，被下架]'
        price:
          type: number
          format: 浮動
        title:
          type: string
        cover:
          type: string
        poster:
          type: string
          description: 海報

• 生成結果：
  

參考資料：
https://liuzm.xyz/2018/09/28/java/open-api-spec/
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#componentsObject
https://www.breakyizhan.com/swagger/2988.html