OpenAPITools 实践

GoCoding
• 阅读 1038

OpenAPITools 可以依据 REST API 描述文件,自动生成服务端桩(Stub)代码、客户端 SDK 代码,及文档等。其是社区版的 Swagger ,差异可见:OpenAPI Generator vs Swagger Codegen

本文将从零开始设计和编写 API 文件,并生成 Go Gin 服务端代码,与 Python SDK 代码。更多语言或框架,也是一样操作的。

快速开始

先熟悉下工具,直接用官方 Docker 镜像生成 Petstore 样例的 Go SDK 代码:

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
-i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \
-g go \
-o /local/out/go

生成代码在当前目录的 ./out/go

打开 Swagger Editor File > Import URL 查看 petstore.yaml API:

OpenAPITools 实践

查看 openapi-generator-cli 用法:

docker run --rm -it \
-v "${PWD}:/local" \
--entrypoint /bin/bash \
openapitools/openapi-generator-cli

ln -s /usr/local/bin/docker-entrypoint.sh /usr/local/bin/openapi-generator
openapi-generator help
openapi-generator help generate

动手实践

设计 RESTful API

打开 Swagger Editor 设计 API:

  • /albums
    • GET - Get all albums
    • POST - Create a new album
  • /albums/:id
    • GET - Get an album by its id
    • PUT - Update an album by its id
    • DELETE - Delete an album by its id

完整 API 描述文件见 spec/api.yaml,主要包含三部分:

1 头部: API 信息

openapi: 3.0.0
info:
  title: Start OpenAPITools
  description: Let's practice designing our api.
  version: 0.1.0
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT.html
servers:
  - url: https://github.com/ikuokuo/start-openapitools

2 中间: paths 及其操作 (get, post, etc.)

paths:
  /albums/{id}:
    get:
      tags:
        - album
      summary: Get an album by its id
      operationId: getAlbum
      parameters:
        - $ref: '#/components/parameters/AlbumId'
      responses:
        200:
          description: Get success, return the album
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Album'
        404:
          description: Album not found

3 底部: 可重用的 components,于文档里 $ref 引用

components:
  parameters:
    AlbumId:
      name: id
      in: path
      description: Album id
      required: true
      schema:
        type: string
  schemas:
    Album:
      title: Album
      type: object
      required:
        - title
        - artist
        - price
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
          maxLength: 200
          minLength: 1
        artist:
          type: string
          maxLength: 100
          minLength: 1
        price:
          type: number
          format: double
          minimum: 0.0
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

具体说明,请阅读 OpenAPI Specification

在线生成代码

可以用线上服务快速生成代码:

以下则是自己动手生成的过程。

生成 Server Stub 代码

生成 Go Gin 桩(Stub)代码:

docker run --rm -it \
-v "${PWD}:/local" \
--entrypoint /bin/bash \
openapitools/openapi-generator-cli

ln -s /usr/local/bin/docker-entrypoint.sh /usr/local/bin/openapi-generator

# Config Options for go-gin-server
#  https://openapi-generator.tech/docs/generators/go-gin-server
openapi-generator config-help -g go-gin-server

openapi-generator generate \
-g go-gin-server \
-i /local/spec/swagger.yaml \
-o /local/out/gin-server \
--additional-properties=packageName=startapi

生成内容:

❯ tree out/gin-server -aF --dirsfirst
out/gin-server
├── .openapi-generator/
├── api/
│   └── openapi.yaml
├── go/
│   ├── README.md
│   ├── api_album.go
│   ├── api_albums.go
│   ├── model_album.go
│   └── routers.go
├── .openapi-generator-ignore
├── Dockerfile
└── main.go

简单实现 GetAlbum 接口,位于 go/api_album.go

// GetAlbum - Get an album by its id
func GetAlbum(c *gin.Context) {
    c.JSON(http.StatusOK, Album{
        Id:        "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        Title:     "Start OpenAPITools",
        Artist:    "GoCoding",
        Price:     0.99,
        CreatedAt: time.Now(),
        UpdatedAt: time.Now(),
    })
}

运行服务:

cd out/gin-server/
# 初始化模块
go mod init github.com/ikuokuo/start-openapitools/gin-server
go mod tidy

# 修改 `main.go` 中的 import 路径
#  sw "github.com/ikuokuo/start-openapitools/gin-server/go"
# 替换成本地路径
go mod edit -replace github.com/ikuokuo/start-openapitools/gin-server/go=./go

运行结果:

❯ go run .
2021/11/05 18:20:00 Server started
[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.

[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:   export GIN_MODE=release
 - using code:  gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /ikuokuo/start-openapitools/ --> github.com/ikuokuo/start-openapitools/gin-server/go.Index (3 handlers)
[GIN-debug] DELETE /ikuokuo/start-openapitools/albums/:id --> github.com/ikuokuo/start-openapitools/gin-server/go.DeleteAlbum (3 handlers)
[GIN-debug] GET    /ikuokuo/start-openapitools/albums/:id --> github.com/ikuokuo/start-openapitools/gin-server/go.GetAlbum (3 handlers)
[GIN-debug] PUT    /ikuokuo/start-openapitools/albums/:id --> github.com/ikuokuo/start-openapitools/gin-server/go.PutAlbum (3 handlers)
[GIN-debug] GET    /ikuokuo/start-openapitools/albums --> github.com/ikuokuo/start-openapitools/gin-server/go.GetAlbums (3 handlers)
[GIN-debug] POST   /ikuokuo/start-openapitools/albums --> github.com/ikuokuo/start-openapitools/gin-server/go.PostAlbums (3 handlers)
[GIN-debug] Listening and serving HTTP on :8080

❯ curl http://localhost:8080/ikuokuo/start-openapitools/
Hello World!

生成 Client SDK 代码

生成 Python SDK 代码:

docker run --rm -it \
-v "${PWD}:/local" \
--entrypoint /bin/bash \
openapitools/openapi-generator-cli

ln -s /usr/local/bin/docker-entrypoint.sh /usr/local/bin/openapi-generator

# Config Options for python
#  https://openapi-generator.tech/docs/generators/python
openapi-generator config-help -g python

openapi-generator generate \
-g python \
-i /local/spec/swagger.yaml \
-o /local/out/py-sdk \
--additional-properties=packageName=startapi \
--additional-properties=library=urllib3

生成内容:

❯ tree out/py-sdk -aF --dirsfirst
out/py-sdk
├── .openapi-generator/
├── docs/
├── startapi/
│   ├── api/
│   │   ├── __init__.py
│   │   ├── album_api.py
│   │   └── albums_api.py
│   ├── apis/
│   │   └── __init__.py
│   ├── model/
│   │   ├── __init__.py
│   │   └── album.py
│   ├── models/
│   │   └── __init__.py
│   ├── __init__.py
│   ├── api_client.py
│   ├── configuration.py
│   ├── exceptions.py
│   ├── model_utils.py
│   └── rest.py
├── test/
├── .gitignore
├── .gitlab-ci.yml
├── .openapi-generator-ignore
├── .travis.yml
├── README.md
├── git_push.sh
├── requirements.txt
├── setup.cfg
├── setup.py
├── test-requirements.txt
└── tox.ini

测试 SDK 使用,调用此前实现的 GetAlbum 接口:

❯ cd out/py-sdk/
❯ python - <<EOF
from startapi import ApiClient, Configuration, apis

config = Configuration(host="http://localhost:8080/ikuokuo/start-openapitools")
with ApiClient(configuration=config) as client:
  api = apis.AlbumApi(client)
  album = api.get_album("xxxxx")
  print(album)
EOF
{'artist': 'GoCoding',
 'created_at': datetime.datetime(2021, 11, 5, 18, 30, 0, 545305, tzinfo=tzoffset(None, 28800)),
 'id': '3fa85f64-5717-4562-b3fc-2c963f66afa6',
 'price': 0.99,
 'title': 'Start OpenAPITools',
 'updated_at': datetime.datetime(2021, 11, 5, 18, 30, 0, 545305, tzinfo=tzoffset(None, 28800))}

最后

实践下来,感觉不错。很多场合,生成 SDK 就够用了。另外,生成自动化测试代码,也值得一试。

GoCoding 个人实践的经验分享,可关注公众号!

点赞
收藏
评论区
推荐文章
blmius blmius
3年前
MySQL:[Err] 1292 - Incorrect datetime value: ‘0000-00-00 00:00:00‘ for column ‘CREATE_TIME‘ at row 1
文章目录问题用navicat导入数据时,报错:原因这是因为当前的MySQL不支持datetime为0的情况。解决修改sql\mode:sql\mode:SQLMode定义了MySQL应支持的SQL语法、数据校验等,这样可以更容易地在不同的环境中使用MySQL。全局s
Easter79 Easter79
3年前
swap空间的增减方法
(1)增大swap空间去激活swap交换区:swapoff v /dev/vg00/lvswap扩展交换lv:lvextend L 10G /dev/vg00/lvswap重新生成swap交换区:mkswap /dev/vg00/lvswap激活新生成的交换区:swapon v /dev/vg00/lvswap
皕杰报表之UUID
​在我们用皕杰报表工具设计填报报表时,如何在新增行里自动增加id呢?能新增整数排序id吗?目前可以在新增行里自动增加id,但只能用uuid函数增加UUID编码,不能新增整数排序id。uuid函数说明:获取一个UUID,可以在填报表中用来创建数据ID语法:uuid()或uuid(sep)参数说明:sep布尔值,生成的uuid中是否包含分隔符'',缺省为
待兔 待兔
4个月前
手写Java HashMap源码
HashMap的使用教程HashMap的使用教程HashMap的使用教程HashMap的使用教程HashMap的使用教程22
Jacquelyn38 Jacquelyn38
3年前
2020年前端实用代码段,为你的工作保驾护航
有空的时候,自己总结了几个代码段,在开发中也经常使用,谢谢。1、使用解构获取json数据let jsonData  id: 1,status: "OK",data: 'a', 'b';let  id, status, data: number   jsonData;console.log(id, status, number )
Stella981 Stella981
3年前
Android So动态加载 优雅实现与原理分析
背景:漫品Android客户端集成适配转换功能(基于目标识别(So库35M)和人脸识别库(5M)),导致apk体积50M左右,为优化客户端体验,决定实现So文件动态加载.!(https://oscimg.oschina.net/oscnet/00d1ff90e4b34869664fef59e3ec3fdd20b.png)点击上方“蓝字”关注我
Wesley13 Wesley13
3年前
00:Java简单了解
浅谈Java之概述Java是SUN(StanfordUniversityNetwork),斯坦福大学网络公司)1995年推出的一门高级编程语言。Java是一种面向Internet的编程语言。随着Java技术在web方面的不断成熟,已经成为Web应用程序的首选开发语言。Java是简单易学,完全面向对象,安全可靠,与平台无关的编程语言。
Stella981 Stella981
3年前
Django中Admin中的一些参数配置
设置在列表中显示的字段,id为django模型默认的主键list_display('id','name','sex','profession','email','qq','phone','status','create_time')设置在列表可编辑字段list_editable
Wesley13 Wesley13
3年前
MySQL部分从库上面因为大量的临时表tmp_table造成慢查询
背景描述Time:20190124T00:08:14.70572408:00User@Host:@Id:Schema:sentrymetaLast_errno:0Killed:0Query_time:0.315758Lock_
Python进阶者 Python进阶者
10个月前
Excel中这日期老是出来00:00:00,怎么用Pandas把这个去除
大家好,我是皮皮。一、前言前几天在Python白银交流群【上海新年人】问了一个Pandas数据筛选的问题。问题如下:这日期老是出来00:00:00,怎么把这个去除。二、实现过程后来【论草莓如何成为冻干莓】给了一个思路和代码如下:pd.toexcel之前把这
GoCoding
GoCoding
Lv1
Go coding in my way :)
文章
32
粉丝
5
获赞
10