在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: 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