OpenAPITools|OpenAPITools 实践 OpenAPITools实践

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：

文章图片

查看 openapi-generator-cli 用法:

docker run --rm -it \ -v "${PWD}:/local" \ --entrypoint /bin/bash \ openapitools/openapi-generator-cliln -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。
在线生成代码
可以用线上服务快速生成代码：

latest stable version: https://api.openapi-generator.tech

以下则是自己动手生成的过程。
生成 Server Stub 代码
生成 Go Gin 桩（Stub）代码：

docker run --rm -it \ -v "${PWD}:/local" \ --entrypoint /bin/bash \ openapitools/openapi-generator-cliln -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-serveropenapi-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-cliln -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 pythonopenapi-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 - <



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

 
  【OpenAPITools|OpenAPITools 实践】GoCoding 个人实践的经验分享，可关注公众号！

 
 


		  	

    
    




    
    
    


推荐阅读

           
                  
              
                  引用是不是修辞手法之一 引用是修辞手法吗 
                
                   
                
              
            

                  
              
                  “人,最大的修养：不随意评论别人,不随意干涉别人”你怎么看？ 
                
                   
                
              
            

                  
              
                  长安区有哪些街道 
                
                   
                
              
            

                  
              
                  海尔空调全国维修电话多少 
                
                   
                
              
            

                  
              
                  诈骗罪退脏不退罪 诈骗罪不退脏会追缴吗？ 
                
                   
                
              
            

                  
              
                  python|python(55)-编码-解码-unicode到底是什么（+repr+） 
                
                   
                
              
            

                  
              
                  上海特产有哪些送人好 到上海买什么特产送人 
                
                   
                
              
            

                  
              
                  多肉花盆怎么选 多肉花盆怎么选视频 
                
                   
                
              
            

                  
              
                  暖雪冰系无限盾怎么玩 
                
                   
                
              
            

                  
              
                  miui10怎么申请内测资格_小米miui10系统内测资格申请教程 
                
                   
                
              
            

                  
              
                  河北十大机场排名 河北有哪些机场离衡水近 
                
                   
                
              
            

                  
              
                  初恋这件小事 
                
                   
                
              
            

                  
              
                  月饼会有要密封吗 
                
                   
                
              
            

                  
              
                  真丝睡衣能用挂烫机吗 
                
                   
                
              
            

                  
              
                  任务分类分析法,按照比较的对象分类,比较分析法包括 
                
                   
                
              
            

                  
              
                  和平精英不掉分卡怎么用 和平精英不掉分卡怎么用不了 
                
                   
                
              
            

                  
              
                  家庭关系与社会关系的区别 
                
                   
                
              
            

                  
              
                  奖励章节详细攻略 密室逃脱极地求生1攻略大全 
                
                   
                
              
            

                  
              
                  显卡背面数字怎么认定，显卡背标 
                
                   
                
              
            

                  
              
                  慈禧与光绪皇帝关系 乾隆娶了自己的女儿 
                
                   
                
              
            

          

不废话，代码实践带你掌握|不废话，代码实践带你掌握 强缓存、协商缓存！ 
 六项精进20180530 
 数据库|SQL行转列方式优化查询性能实践 
 【Day31课后实践】 
 2021—3—8日教练实践总结&呼吸练习&觉察日记 
 湖州大学生实践团开展系列活动践行生态文明理念 
 好的思维需要实践 
 服务注册与服务发现的最简单实践 
 回归|金融数值方法之回归计算-python实践 
 《管理的实践》第5章|《管理的实践》第5章 企业是什么