开发接口文档

swag 文档地址

生成开发文档命令

swag init

注释文档格式化命令

swag fmt

关于 Api

参考 Restful 设计风格。

请求方法指南

五个常用的 HTTP 动词，用于表示对于资源的具体操作类型：

• GET（SELECT）：从服务器取出资源（一项或多项）。
• PUT（CREATE）：在服务器新建一个资源。
• POST（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
• PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
• DELETE（DELETE）：从服务器删除资源。

还有两个不常用的HTTP动词：

• HEAD：获取资源的元数据。
• OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

分页查询

接口应该提供如下参数过滤返回结果：

• sort_by 排序字段列表，可以为字段指定如下前缀实现排序：
  • + 表示查询结果按该字段的升序进行排序，为默认前缀，可省略；
  • - 表示查询结果按该字段的降序进行排序。
• page 页码，可选，默认值为 1
• per_page 页容量，可选，默认值为 30

客户端通过 QueryString 方式提交上述参数来分页查询。