Skip to content

Commit

Permalink
add swagger
Browse files Browse the repository at this point in the history
  • Loading branch information
Away0x committed May 15, 2019
1 parent 9c21381 commit 40df915
Show file tree
Hide file tree
Showing 15 changed files with 769 additions and 15 deletions.
2 changes: 2 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,11 @@ install:
go mod download

dev:
# go get github.com/pilu/fresh
fresh -c ./fresh.conf

api-doc:
# go get -u github.com/swaggo/swag/cmd/swag
swag init

mock:
Expand Down
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
# Gin BBS App

- [访问地址](http://www.frontendgo.com:8889)
- [API 文档](http://www.frontendgo.com:8889/swagger/index.html)

## 项目目录结构
<details>
<summary>展开查看</summary>
Expand All @@ -19,6 +22,8 @@
├── public 项目静态文件
├── docs swagger api doc
├── resources 前端源码
│ └── view go 模板文件
Expand Down Expand Up @@ -58,6 +63,7 @@
- [x] 文件上传
- [x] 发送短信
- [x] 微信登录
- [x] swagger api 文档
- [ ] 基于 Vue 的管理员后台系统


Expand Down
8 changes: 8 additions & 0 deletions app/controllers/api/authorization/authorization.go
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,14 @@ var (
)

// Store 第三方登录
// @Summary 第三方登录
// @Tags authorization
// @Accept json
// @Produce json
// @Param social_type path string true "social_type in [weixin]"
// @Param json body authorization.Authorization true "微信 access_token openid 和 code,要么传 access_token openid 要么只传 code"
// @Success 200 {object} controllers.Response "{"token": 1}"
// @Router /api/socials/authorizations/{social_type} [post]
func Store(c *gin.Context) {
var req *authorizationRequest.Authorization
if err := c.ShouldBind(&req); err != nil {
Expand Down
1 change: 0 additions & 1 deletion app/controllers/api/authorization/weixin__.go

This file was deleted.

11 changes: 11 additions & 0 deletions app/controllers/api/captcha/captcha.go
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,18 @@ import (
"github.com/gin-gonic/gin"
)

type storeParams struct {
Phone string
}

// Store 图片验证码
// @Summary 图片验证码
// @Tags captchas
// @Accept json
// @Produce json
// @Param phone body captcha.storeParams true "手机号"
// @Success 200 {object} controllers.Response "{"captcha_image_content": "http://localhost:8889/captcha/izzUb7f1mYEsi5wModz5.png","captcha_key": "captcha_W4PtXdQQ6KFXvs3","expired_at": "2019-05-15 17:23:21"}"
// @Router /api/captchas [post]
func Store(c *gin.Context) {
phone, ok := requests.RunPhoneValidate(c)
if !ok {
Expand Down
7 changes: 7 additions & 0 deletions app/controllers/api/user/user.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,13 @@ import (
)

// Store 用户注册
// @Summary 用户注册
// @Tags users
// @Accept json
// @Produce json
// @Param req body user.User true "req"
// @Success 200 {object} controllers.Response "{}"
// @Router /api/users [post]
func Store(c *gin.Context) {
var req request.User
if err := c.ShouldBindJSON(&req); err != nil {
Expand Down
7 changes: 7 additions & 0 deletions app/controllers/api/verification_code/verification_code.go
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,13 @@ import (
)

// Store 发送短信
// @Summary 发送短信
// @Tags verificationCodes
// @Accept json
// @Produce json
// @Param req body vericode.VerificationCode true "req"
// @Success 200 {object} controllers.Response "{"key": "verificationCode_xxxxx","debug_sms_result": "xxxx","expired_at": "2019-05-15 17:23:21"}"
// @Router /api/verificationCodes [post]
func Store(c *gin.Context) {
// 验证图片验证码
var req vericode.VerificationCode
Expand Down
2 changes: 1 addition & 1 deletion app/requests/api/authorization/authorization.go
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ func (a *Authorization) RegisterValidators() validate.ValidatorMap {
func (a *Authorization) Run() (*weixin.WeixinUserInfo, *errno.Errno) {
if config.AppConfig.WeixinAppID == "" || config.AppConfig.WeixinAppSecret == "" {
log.Warn("weixin config error: 未配置 WEIXIN CONFIG,请检查 config.yaml 配置")
return nil, errno.InternalServerError
return nil, errno.New(errno.InternalServerError, "weixin config error: 未配置 WEIXIN CONFIG,请检查 config.yaml 配置")
}
var (
err error
Expand Down
278 changes: 278 additions & 0 deletions docs/docs.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,278 @@
// GENERATED BY THE COMMAND ABOVE; DO NOT EDIT
// This file was generated by swaggo/swag at
// 2019-05-15 17:30:16.6310762 +0800 CST m=+5.150093201

package docs

import (
"bytes"

"github.com/alecthomas/template"
"github.com/swaggo/swag"
)

var doc = `{
"swagger": "2.0",
"info": {
"description": "{{.Description}}",
"title": "{{.Title}}",
"contact": {},
"license": {},
"version": "{{.Version}}"
},
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {
"/api/captchas": {
"post": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"captchas"
],
"summary": "图片验证码",
"parameters": [
{
"description": "手机号",
"name": "phone",
"in": "body",
"required": true,
"schema": {
"type": "object",
"$ref": "#/definitions/captcha.storeParams"
}
}
],
"responses": {
"200": {
"description": "{\"captcha_image_content\": \"http://localhost:8889/captcha/izzUb7f1mYEsi5wModz5.png\",\"captcha_key\": \"captcha_W4PtXdQQ6KFXvs3\",\"expired_at\": \"2019-05-15 17:23:21\"}",
"schema": {
"type": "object",
"$ref": "#/definitions/controllers.Response"
}
}
}
}
},
"/api/socials/authorizations/{social_type}": {
"post": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"authorization"
],
"summary": "第三方登录",
"parameters": [
{
"type": "string",
"description": "social_type in [weixin]",
"name": "social_type",
"in": "path",
"required": true
},
{
"description": "微信 access_token openid 和 code,要么传 access_token openid 要么只传 code",
"name": "json",
"in": "body",
"required": true,
"schema": {
"type": "object",
"$ref": "#/definitions/authorization.Authorization"
}
}
],
"responses": {
"200": {
"description": "{\"token\": 1}",
"schema": {
"type": "object",
"$ref": "#/definitions/controllers.Response"
}
}
}
}
},
"/api/users": {
"post": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"users"
],
"summary": "用户注册",
"parameters": [
{
"description": "req",
"name": "req",
"in": "body",
"required": true,
"schema": {
"type": "object",
"$ref": "#/definitions/user.User"
}
}
],
"responses": {
"200": {
"description": "{}",
"schema": {
"type": "object",
"$ref": "#/definitions/controllers.Response"
}
}
}
}
},
"/api/verificationCodes": {
"post": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"verificationCodes"
],
"summary": "发送短信",
"parameters": [
{
"description": "req",
"name": "req",
"in": "body",
"required": true,
"schema": {
"type": "object",
"$ref": "#/definitions/vericode.VerificationCode"
}
}
],
"responses": {
"200": {
"description": "{\"key\": \"verificationCode_xxxxx\",\"debug_sms_result\": \"xxxx\",\"expired_at\": \"2019-05-15 17:23:21\"}",
"schema": {
"type": "object",
"$ref": "#/definitions/controllers.Response"
}
}
}
}
}
},
"definitions": {
"authorization.Authorization": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"code": {
"type": "string"
},
"openid": {
"type": "string"
}
}
},
"captcha.storeParams": {
"type": "object",
"properties": {
"phone": {
"type": "string"
}
}
},
"controllers.Response": {
"type": "object",
"properties": {
"code": {
"description": "自定义的异常码",
"type": "integer"
},
"data": {
"description": "具体响应数据\n- 无数据时,默认返回一个 {}\n- 如果是列表数据建议使用 ListData 类型\n- 不需分页的列表类型时,也建议 data.list 这样响应",
"type": "object"
},
"errors": {
"description": "具体错误信息\n- 只用于调试的,前端不应使用该值,因为其可能会不存在",
"type": "object"
},
"message": {
"description": "错误描述",
"type": "string"
}
}
},
"user.User": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"password": {
"type": "string"
},
"verification_code": {
"type": "string"
},
"verification_key": {
"type": "string"
}
}
},
"vericode.VerificationCode": {
"type": "object",
"properties": {
"captcha_code": {
"type": "string"
},
"captcha_key": {
"type": "string"
}
}
}
}
}`

type swaggerInfo struct {
Version string
Host string
BasePath string
Title string
Description string
}

// SwaggerInfo holds exported Swagger Info so clients can modify it
var SwaggerInfo swaggerInfo

type s struct{}

func (s *s) ReadDoc() string {
t, err := template.New("swagger_info").Parse(doc)
if err != nil {
return doc
}

var tpl bytes.Buffer
if err := t.Execute(&tpl, SwaggerInfo); err != nil {
return doc
}

return tpl.String()
}

func init() {
swag.Register(swag.Name, &s{})
}
Loading

0 comments on commit 40df915

Please sign in to comment.