openapi-generator入门及快速实践

1 - 什么是openapi

这里的openapi指狭义的openapi, 即:

OpenAPI规范（以前称为Swagger规范）是一种机器可读接口文件的规范，用于描述，生成，使用和可视化RESTful Web服务。它以前是Swagger框架的一部分，在2016年成为一个单独的项目，由Linux基金会的一个开源协作项目OpenAPI Initiative监督。

目前openapi常用的规范有v2和v3, 最明显的区别在api.yml的第一行上(

swagger: "2.0"  # v2
openapi: "3.0.0" # v3

目前v3的完整规范可以参考这里

v2的完整规范可以参考这里

提供一个User服务的典型示例文件, 并带有一定的注释, 本文之后的实践部分也将基于如下的api进行

# openapi 标准版本(v2)
swagger: "2.0"
# 一些基本信息
info:
  title: 'swagger test'
  description: ''
  version: '0.1'
  termsOfService: 'http://swagger.io/terms/'
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
# 协议: "http", "https", "ws", "wss"
schemes:
  - "http"
# 基本路径: 一般是<host><basePath><paths>, 如localhost:8888/api/user/save
basePath: /api
# api服务的路径与详细参数
paths:
  /user/save: # 路径
    post: # 请求
      tags: # tag必须唯一, 用于对接口进行分类
        - "User"
      summary: "save user"
      description: "return init password"
      operationId: saveUser # 一般各种codegen工具会根据这个生成方法
      produces:
        - "application/json"
      parameters: # 参数
        -   in: body
            name: "user"
            required: true
            schema:
              $ref: "#/definitions/User" # 表示引用definitions/User这个Object作为该参数
      responses: # 返回值和返回值格式
        200:
          description: "operate success"
          schema:
            type: object
            $ref: "#/definitions/Response"
        400:
          description: "operate down"
          schema:
            type: object
            $ref: "#/definitions/Response"
    get:
      operationId: getUser
      produces:
        - "application/json"
      responses:
        200:
          description: "get user lists"
          schema:
            type: array
            $ref: "#/definitions/Users"

# 对各种Object作定义
definitions:
  Response:
    type: object
    properties:
      success:
        type: boolean
      code:
        type: string
      message:
        type: string
      data:
        type: object

  User:
    type: object
    required:
      - userNumber
      - userName
    properties:
      id:
        type: integer
        format: int64
      userNumber:
        type: string
        pattern: \d{8}
      userName:
        type: string
        pattern: ^[a-zA-Z]{1,40}$
      phone:
        type: string
        pattern: (\d{10})?
      userStatus:
        type: string
      operatorNumber:
        type: string

  Users:
    type: array
    items:
      $ref: "#/definitions/User"

更多信息请参考其他博客和官方文档，总之openapi的规范考虑的非常全面，基本可以定义出一个api的所有详细信息，让开发不再模糊，开发者之间不再产生分歧。

2 - openapi-generator

项目地址

简单来说，openapi-generator的功能就是根据标准的api文档，生成对应的服务端或者客户端代码的工具，并且支持许多不同的语言和框架。

目前openapi-generator支持生成这些语言的代码。

和swagger codegen的比较

swagger-codegen的功能和openapi-generator几乎一致

根据openapi-generator官网所言

OpenAPI Generator is a fork of swagger-codegen between version 2.3.1 and 2.4.0.

openapi-generator是根据swagger-codegen的分叉版本, 分叉原因见

总结就是:

1. 开发人员理念不一致
2. 希望更快的发布和更新版本
3. 希望进行社区驱动(openapi-generator)而不是公司驱动(swagger-codegen)

根据openhub的比较

前者更活跃一点

3 - openapi-generator-maven-plugin

openapi-generator-maven-plugin是一个openapi-generator的子项目, 同时也是java使用openapi开发客户端或者服务端的神器。

它的主要功能是在java项目构建时运行该插件, 在target中生成相应的代码, 免去手动执行cli的工作了, 并且不会影响到项目代码本身。

readme文档: https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-maven-plugin/README.md

code talks，我基于jdk1.8和openapi-generator-maven-plugin分别写了java的客户端(with feign client)和服务端(with springboot)的最小示例，供参考学习。

demo

项目地址