###接口描述 (@SWGGet, @SWGPost 等) 常用字段:
summary - string
接口的简要介绍,会显示在接口标头上,不能超过120个字符
description - string
接口的详细介绍
externalDocs - string
外部文档链接
operationId - string
全局唯一的接口标识
consumes - [string]
接口接收的MIME类型
produces - [string]
接口返回的MIME类型,如 application/json
schemes - [string]
接口所支持的协议,取值仅限: "http", "https", "ws", "wss"
parameters - [Parameter Object | Reference Object]
参数列表
参数描述 (@SWGParameter) 常用字段
name - string
参数名. 通过路径传参(in 取值 "path")
in - string
参数从何处来. 必填. 取值仅限: "query", "header", "path", "formData", "body"
description - string
参数描述. 最好别太长
type - string
参数类型. 取值仅限: "string", "number", "integer", "boolean", "array", "file"
required - boolean
参数是否必须. 通过路径传参(in 取值 "path")时必须为 true.
default - *
默认值. 在你打算把参数通过 path 传递时规矩挺多,我没用到.用到的同学自己看文档吧.
swagger 在GOALNG 与 PHP 中模型的定义
golang 中 struct 即为一个模型定义, 如:
type User struct {
Id uint `gorm:"primary_key" json:"id"`
Username string `gorm:"unique_index" json:"username"`
Password string `json:"-"`
State string `json:"state"`
CreatedAt time.Time `json:"created_at" swaggertype:"primitive,integer"`
UpdatedAt time.Time `json:"updated_at" swaggertype:"primitive,integer"`
DeletedAt *time.Time `sql:"index" json:"deleted_at"`
UserDetail *UserDetail `json:"user_detail"`
Posts []Post `json:"posts"`
}
type UserDetail struct {
Id uint `gorm:"primary_key" json:"id"`
UserId uint `json:"user_id"`
NickName string `json:"nick_name"`
Sex int `json:"sex"`
Avatar string `json:"avatar"`
Profile string `json:"profile"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
DeletedAt *time.Time `sql:"index" json:"deleted_at"`
}
type Post struct {
Id uint `gorm:"primary_key" json:"id"`
UserId uint `json:"user_id"`
Title string `json:"title"`
Body string `json:"body"`
Link string `json:"link"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
DeletedAt *time.Time `sql:"index" json:"deleted_at"`
}
在swagger go 中如何建全局的 jwt 或者 session值 进行接口的try it out
// @securityDefinitions.apikey ApiKeyAuth
// @in query|header
// @name token|Authorization|Cookie
// @Security ApiKeyAuth
// @Summary 概括
// @Description 描述
// @Tags 分类
// @Accept json|xml|plain|html..
// @Produce json|xml|plain|html|jpg ..
// @Param name query|header|path|body|formData valueType(int|string|[]int...) true|false "comment"
// @response code {object} dataType "comment"
// @Router /user/info [get]
func userInfo() {}
php 中定义模型可以通过类去定义
<?php
/**
* @SWG\Definition(type="object", @SWG\Xml(name="User"))
*/
class User {
/**
* @SWG\Property()
* @var int
*/
public $id;
/**
* @SWG\Property(example="test")
* @var string
*/
public $username;
/**
* @SWG\Property(format="int32", example="sha1 encode",description="这个是用户帐号")
* @var int
*/
public $password;
/**
* @SWG\Property(format="int32",description="1 正常 0 关闭")
* @var int
*/
public $state;
/**
* @SWG\Property(format="Date",example = "2010-01-01")
* @var Date
*/
public $createAt;
/**
* @SWG\Property(format="Date" ,example="2010-01-01")
* @var Date
*/
public $updateAt;
/**
* @SWG\Property(format="Date")
* @var Date
*/
public $deleteAt;
/**
* @SWG\Property(ref="#/definitions/UserDetail")
* @var object
*/
public $userDetail;
/**
* @SWG\Property(@SWG\Items(ref="#/definitions/Post"))
* @var array
*/
public $posts;
}
/**
* @SWG\Definition(type="object", @SWG\Xml(name="UserDetail"))
*/
class UserDetail {
/**
* @SWG\Property()
* @var int
*/
public $id;
/**
* @SWG\Property()
* @var int
*/
public $userId;
/**
* @SWG\Property(format="int32")
* @var string
*/
public $nickname;
/**
* @SWG\Property(format="int32")
* @var int
*/
public $sex;
/**
* @SWG\Property(format="int32")
* @var string
*/
public $avatar;
/**
* @SWG\Property(format="int32")
* @var string
*/
public $profile;
/**
* @SWG\Property(format="Date")
* @var Date
*/ public $createAt;
/**
* @SWG\Property(format="Date")
* @var Date
*/
public $updateAt;
/**
* @SWG\Property(format="Date")
* @var Date
*/
public $deleteAt;
}
/**
* @SWG\Definition(type="object", @SWG\Xml(name="Post"))
*/
class Post {
/**
* @SWG\Property()
* @var int
*/
public $id;
/**
* @SWG\Property()
* @var int
*/
public $userId;
/**
* @SWG\Property()
* @var string
*/
public $title;
/**
* @SWG\Property(format="int32")
* @var int
*/
public $body;
/**
* @SWG\Property(format="int32")
* @var int
*/
public $link;
/**
* @SWG\Property(format="Date")
* @var Date
*/
public $createAt;
/**
* @SWG\Property(format="Date")
* @var Date
*/
public $updateAt;
/**
* @SWG\Property(format="Date")
* @var Date
*/
public $deleteAt;
}
or
/**
* @SWG\Definition(
* definition="Person",
* type="object",
* required={"username"},
* @SWG\Property(property="id",example="title id",type="integer",description="主键id"),
* @SWG\Property(property="userId",type="integer",description="用户id"),
* @SWG\Property(property="title",type="string",description="标题"),
* @SWG\Property(property="body",type="string",description="内容"),
* @SWG\Property(property="link",type="string",description="链接"),
* @SWG\Property(property="avatarBase64PNG",type="string",format="byte"),
* @SWG\Property(property="createdAt",type="string",description="创建时间",format="date"),
* @SWG\Property(property="code",type="string",enum={"DBERR", "NTERR", "UNERR"}),
* @SWG\Property(property="updatedAt",type="string",description="更新时间",format="dateTime"),
* @SWG\Property(property="deletedAt",type="string",description="删除时间"),
* )
*/
/**
* @SWG\Definition(
* definition="Homepage",
* type="object",
* required={},
* @SWG\Property(property="page",example="1",type="integer",description="页码"),
* @SWG\Property(property="limit",type="integer",description="每页数"),
* @SWG\Property(property="count",type="integer",description="总数"),
* @SWG\Property(property="data",type="object",
* allOf = {
* @SWG\Schema(ref="#/definitions/Person"),
* @SWG\Schema(@SWG\Property(property="post",type="object",ref="#/definitions/Post"))
* }),
* )
*/
php 与 go 生成的模型是类似如下图, 在代码可读性方面 golang要好很多
image.png
这样在response返回时, 可以直接用 引用模型就可以了
在golang 中 使用 @Success 200 {object} controller.User 即可引用模型 , 在PHP中 使用 ref="#/definitions/User" 的方式引用模型
网友评论