基于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依赖：

        
            
                org.springframework.boot
                spring-boot-maven-plugin
            
            
                
                org.openapitools
                openapi-generator-maven-plugin
                3.3.1
                
                    
                        
                            generate
                        
                        
                            ${project.basedir}/src/swagger/马上开课openapi3.0文档.yaml
                            spring
                            com.example.openapigenerator.rest
                            com.example.openapigenerator.rest.dto
                            
${project.basedir}
                            ApiUtil.java
                            
                                true
                            
                        
                    
                
            
        
    

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

• 测试使用的yaml文件:

openapi: 3.0.0
info:
  title: xxxxAPI文档
  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: 'http://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