ICode9

精准搜索请尝试: 精确搜索
首页 > 其他分享> 文章详细

【转】YApi结合swag管理和生成go项目restful API文档

2022-08-27 18:02:17  阅读:200  来源: 互联网

标签:account err YApi swag json API accounts go httputil


 

原文:https://blog.csdn.net/tuobicui6522/article/details/102980653

 

swag命令安装:

 

go install github.com/swaggo/swag/cmd/swag@latest




 

swag命令对应的github库:https://github.com/swaggo/swag

 

 

 

 

 

 用yapi在线调用接口测试

 

 

aaa

 

-----------------------------------------

 

YApi结合swag管理go项目API文档

准备
什么是OpenAPI?Swagger是什么?
安装和了解swag
YApi教程
docker部署YApi
项目demo
├── controller
│ ├── accounts.go
│ └── controller.go
├── docs
│ ├── docs.go
│ ├── swagger.json
│ └── swagger.yaml
├── go.mod
├── httputil
│ └── error.go
├── main.go
└── model
└── account.go

main.go

package main

import (
"demo/controller"
_ "demo/docs"

"github.com/gin-gonic/gin"
swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
)

// @title Swagger Example API
// @version 1.0
// @description This is a sample server demo server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8080
// @BasePath /api/v1

func main() {
r := gin.Default()

c := controller.NewController()

v1 := r.Group("/api/v1")
{
accounts := v1.Group("/accounts")
{
accounts.GET(":id", c.ShowAccount)
accounts.POST("", c.AddAccount)
}
}
// 先用swag init 生成docs目录
// http://localhost:8080/swagger/index.html 可以看swagger ui的文档
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
r.Run(":8080")
}


controller/controller.go

package controller

// Controller example
type Controller struct {
}

// NewController example
func NewController() *Controller {
return &Controller{}
}

// Message example
type Message struct {
Message string `json:"message" example:"message"`
}

controller/accounts.go

package controller

import (
"demo/httputil"
"demo/model"
"net/http"
"strconv"

"github.com/gin-gonic/gin"
)

// ShowAccount godoc
// @Summary Show a account
// @Description get string by ID
// @Tags accounts
// @Accept json
// @Produce json
// @Param id path int true "Account ID"
// @Success 200 {object} model.Account
// @Failure 400 {object} httputil.HTTPError
// @Failure 404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Router /accounts/{id} [get]
func (c *Controller) ShowAccount(ctx *gin.Context) {
id := ctx.Param("id")
aid, err := strconv.Atoi(id)
if err != nil {
httputil.NewError(ctx, http.StatusBadRequest, err)
return
}
account, err := model.AccountOne(aid)
if err != nil {
httputil.NewError(ctx, http.StatusNotFound, err)
return
}
ctx.JSON(http.StatusOK, account)
}

// AddAccount godoc
// @Summary Add a account
// @Description add by json account
// @Tags accounts
// @Accept json
// @Produce json
// @Param account body model.AddAccount true "Add account"
// @Success 200 {object} model.Account
// @Failure 400 {object} httputil.HTTPError
// @Failure 404 {object} httputil.HTTPError
// @Failure 500 {object} httputil.HTTPError
// @Router /accounts [post]
func (c *Controller) AddAccount(ctx *gin.Context) {
var addAccount model.AddAccount
if err := ctx.ShouldBindJSON(&addAccount); err != nil {
httputil.NewError(ctx, http.StatusBadRequest, err)
return
}
if err := addAccount.Validation(); err != nil {
httputil.NewError(ctx, http.StatusBadRequest, err)
return
}
// Name以外的字段仅用来演示
account := model.Account{
Name: addAccount.Name,
}
lastID, err := account.Insert()
if err != nil {
httputil.NewError(ctx, http.StatusBadRequest, err)
return
}
account.ID = lastID
ctx.JSON(http.StatusOK, account)
}


httputil/error.go


package httputil

import "github.com/gin-gonic/gin"

// NewError example
func NewError(ctx *gin.Context, status int, err error) {
er := HTTPError{
Code: status,
Message: err.Error(),
}
ctx.JSON(status, er)
}

// HTTPError example
type HTTPError struct {
Code int `json:"code" example:"400"`
Message string `json:"message" example:"status bad request"`
}


model/account.go

package model

import (
"errors"
"fmt"

uuid "github.com/satori/go.uuid"
)

// Account example
type Account struct {
ID int `json:"id" example:"1" format:"int64"`
Name string `json:"name" example:"account name"`
UUID uuid.UUID `json:"uuid" example:"550e8400-e29b-41d4-a716-446655440000" format:"uuid"`
}

// example
var (
ErrNameInvalid = errors.New("name is empty")
ErrNoRow = errors.New("no rows in result set")
)

// AddAccount example
// Name以外的字段仅用来测试 struct tag 的作用
type AddAccount struct {
Name string `json:"name" example:"Tom" format:"string" binding:"required" minLength:"1" maxLength:"16"` // 用户名
Age int `json:"age" example:"10" binding:"required" minimum:"1" maximum:"150" default:"10"` // 年龄
Height float64 `json:"height" example:"1.80" binding:"required" minimum:"0.0" maximum:"9.99"` // 身高,单位米
Status string `json:"status" enums:"healthy,ill"` // 状态
}

// Validation example
func (a AddAccount) Validation() error {
switch {
case len(a.Name) == 0:
return ErrNameInvalid
default:
return nil
}
}

// AccountOne example
func AccountOne(id int) (Account, error) {
for _, v := range accounts {
if id == v.ID {
return v, nil
}
}
return Account{}, ErrNoRow
}

// Insert example
func (a Account) Insert() (int, error) {
accountMaxID++
a.ID = accountMaxID
a.Name = fmt.Sprintf("account_%d", accountMaxID)
accounts = append(accounts, a)
return accountMaxID, nil
}

var accountMaxID = 3
var accounts = []Account{
{ID: 1, Name: "account_1"},
{ID: 2, Name: "account_2"},
{ID: 3, Name: "account_3"},
}


swag生成API文档
在项目根目录下执行以下命令生成docs目录

swag init
1
YApi管理项目的API的文档
打开localhost:40001登录YApi

在个人空间下创建一个test分组,组长填自己的用户名好了

在test分组下创建一个项目demo

导入上面生成的docs/swagger.json文件,如图

 

 


查看导入的接口

 

 

 

 

 

 

 


在上图可以看到,model.AddAccount结构体附属的struct tag 和字段的注释已经变成文档的一部分了

同时还可以像postman一样测试接口,其他功能就不说了,留待你们自己挖掘

 

 


总结
在go项目中,开发人员只要把代码的注解写好,然后用swag生成相关文件,YApi导入json文件,整个项目的接口管理变的清晰简单。不过文档没有swagger ui展示的那么详细,可以看情况搭配使用。
————————————————
版权声明:本文为CSDN博主「米兰的小铁匠1943」的原创文章,遵循CC 4.0 BY-SA版权协议,转载请附上原文出处链接及本声明。
原文链接:https://blog.csdn.net/tuobicui6522/article/details/102980653

标签:account,err,YApi,swag,json,API,accounts,go,httputil
来源: https://www.cnblogs.com/oxspirt/p/16631056.html

本站声明: 1. iCode9 技术分享网(下文简称本站)提供的所有内容,仅供技术学习、探讨和分享;
2. 关于本站的所有留言、评论、转载及引用,纯属内容发起人的个人观点,与本站观点和立场无关;
3. 关于本站的所有言论和文字,纯属内容发起人的个人观点,与本站观点和立场无关;
4. 本站文章均是网友提供,不完全保证技术分享内容的完整性、准确性、时效性、风险性和版权归属;如您发现该文章侵犯了您的权益,可联系我们第一时间进行删除;
5. 本站为非盈利性的个人网站,所有内容不会用来进行牟利,也不会利用任何形式的广告来间接获益,纯粹是为了广大技术爱好者提供技术内容和技术思想的分享性交流网站。

专注分享技术,共同学习,共同进步。侵权联系[81616952@qq.com]

Copyright (C)ICode9.com, All Rights Reserved.

ICode9版权所有