OpenAPITools can automatically generate server-side stub code, client-side SDK code, and documentation based on REST API description files. It is the community version of Swagger , the difference can be seen: OpenAPI Generator vs Swagger Codegen .
This article will design and write API files from scratch, and generate Go Gin server code and Python SDK code. More languages or frameworks do the same.
Quick start
Get familiar with the tools first, and directly use the official Docker image to generate the Go SDK code of the Petstore sample:
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/goThe generated code is ./out/go in the current directory.
Open Swagger Editor File > Import URL view petstore.yaml API:
View openapi-generator-cli usage:
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 generateHands
Design RESTful API
Open Swagger Editor design 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
For the complete API description file, see spec/api.yaml , which mainly contains three parts:
1 Header: API information
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-openapitools2 Middle: paths and its operations ( 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 found3 Bottom: components , referenced in the document $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-timeFor specific instructions, please read OpenAPI Specification .
Generate code online
You can use online services to quickly generate code:
- latest stable version: https://api.openapi-generator.tech
The following is the process of doing it yourself.
Generate Server Stub code
Generate Go Gin stub code:
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=startapiGenerated content:
❯ 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.goSimple implementation of the GetAlbum interface, located at 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(),
})
}Run the service:
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=./gooperation result:
❯ 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!Generate Client SDK code
Generate Python SDK code:
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=urllib3Generated content:
❯ 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.iniTo test the use of the SDK, call the previously implemented interface 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))}finally
After practice, it feels good. In many cases, it is sufficient to generate the SDK. In addition, generating automated test code is also worth a try.
GoCoding personal practice experience sharing, please follow the official account!
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用。你还可以使用@来通知其他用户。