Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/zeromicro/goctl-swagger
https://github.com/zeromicro/goctl-swagger
Last synced: 4 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/zeromicro/goctl-swagger
- Owner: zeromicro
- License: mit
- Created: 2021-01-01T12:25:39.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-08-08T10:43:30.000Z (6 months ago)
- Last Synced: 2025-02-03T17:50:05.095Z (11 days ago)
- Language: PHP
- Size: 6.88 MB
- Stars: 219
- Watchers: 6
- Forks: 141
- Open Issues: 51
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-zero - goctl-swagger - goctl swagger plugin (Tools and plugins for [go-zero](https://github.com/tal-tech/go-zero))
README
# goctl-swagger
### 1. 编译goctl-swagger插件
```
GOPROXY=https://goproxy.cn/,direct go install github.com/zeromicro/goctl-swagger@latest
```
### 2. 配置环境
将$GOPATH/bin中的goctl-swagger添加到环境变量
### 3. 使用姿势
* 创建api文件
```go
info(
title: "type title here"
desc: "type desc here"
author: "type author here"
email: "type email here"
version: "type version here"
)
type (
RegisterReq {
Username string `json:"username"`
Password string `json:"password"`
Mobile string `json:"mobile"`
}
LoginReq {
Username string `json:"username"`
Password string `json:"password"`
}
UserInfoReq {
Id string `path:"id"`
}
UserInfoReply {
Name string `json:"name"`
Age int `json:"age"`
Birthday string `json:"birthday"`
Description string `json:"description"`
Tag []string `json:"tag"`
}
UserSearchReq {
KeyWord string `form:"keyWord"`
}
)
service user-api {
@doc(
summary: "注册"
)
@handler register
post /api/user/register (RegisterReq)
@doc(
summary: "登录"
)
@handler login
post /api/user/login (LoginReq)
@doc(
summary: "获取用户信息"
)
@handler getUserInfo
get /api/user/:id (UserInfoReq) returns (UserInfoReply)
@doc(
summary: "用户搜索"
)
@handler searchUser
get /api/user/search (UserSearchReq) returns (UserInfoReply)
}
```
* 生成swagger.json 文件
```shell script
goctl api plugin -plugin goctl-swagger="swagger -filename user.json" -api user.api -dir .
```
* 指定Host，basePath，schemes [api-host-and-base-path](https://swagger.io/docs/specification/2-0/api-host-and-base-path/)
```shell script
goctl api plugin -plugin goctl-swagger="swagger -filename user.json -host 127.0.0.2 -basepath /api -schemes https,wss" -api user.api -dir .
```
* swagger ui 查看生成的文档
```shell script
docker run --rm -p 8083:8080 -e SWAGGER_JSON=/foo/user.json -v $PWD:/foo swaggerapi/swagger-ui
```
* Swagger Codegen 生成客户端调用代码(go,javascript,php)
```shell script
for l in go javascript php; do
docker run --rm -v "$(pwd):/go-work" swaggerapi/swagger-codegen-cli generate \
-i "/go-work/rest.swagger.json" \
-l "$l" \
-o "/go-work/clients/$l"
done
```