版权声明：本文为博主原创文章，未经博主允许不得转载。 https://blog.csdn.net/yzy199391/article/details/84023982
在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