扫码订阅《 》或入驻星球,即可阅读文章!

GOLANG ROADMAP

阅读模式

  • 沉浸
  • 自动
  • 日常
首页
Go友会
  • 城市
  • 校园
Go学院
  • Go小课
  • Go小考
  • Go实战
  • 精品课
Go求职
  • 求职辅导🔥
  • Offer收割社群
  • 企业题库
  • 面试宝典
Go宝典
  • 在线宝典
  • B站精选
  • 推荐图书
  • 每日博文
Go仓库
实验区
  • Go周边
  • Go下载
  • Go月刊
消息
更多
  • 用户中心

    • 我的信息
    • 推广返利
  • 玩转星球

    • 星球介绍
    • 角色体系
    • 星主权益
  • 支持与服务

    • 联系星主
    • 成长记录
    • 常见问题
    • 吐槽专区
  • 合作交流

    • 渠道合作
    • 课程入驻
    • 友情链接
author-avatar

GOLANG ROADMAP


首页
Go友会
  • 城市
  • 校园
Go学院
  • Go小课
  • Go小考
  • Go实战
  • 精品课
Go求职
  • 求职辅导🔥
  • Offer收割社群
  • 企业题库
  • 面试宝典
Go宝典
  • 在线宝典
  • B站精选
  • 推荐图书
  • 每日博文
Go仓库
实验区
  • Go周边
  • Go下载
  • Go月刊
消息
更多
  • 用户中心

    • 我的信息
    • 推广返利
  • 玩转星球

    • 星球介绍
    • 角色体系
    • 星主权益
  • 支持与服务

    • 联系星主
    • 成长记录
    • 常见问题
    • 吐槽专区
  • 合作交流

    • 渠道合作
    • 课程入驻
    • 友情链接
  • Go工程化规范设计

    • 前言
    • 开源规范
    • 文档规范
    • 版本规范
    • Git规范
    • 目录结构
    • 编码规范
    • 代码测试
    • 性能分析
    • API 设计
    • 项目管理
    • 研发流程
    • 参考资料
  • Go工程化标准实践

    • 前言
    • 项目结构
    • API 设计
    • 配置管理
    • 模块管理
    • 测试
    • 参考资料

扫码订阅《 》或入驻星球,即可阅读文章!

文档规范


Kyle

# README 文档

README.md 用于介绍项目的功能、安装、部署、使用。

建议使用 readme.so (opens new window) 生成。

# 项目文档

要求易读和可快速定位目标内容,可提供中文与英文版本:

  • 开发文档:描述项目开发流程,包括如何搭建开发环境、构建二进制文件、测试、部署等。
  • 用户文档:软件的使用文档,对象一般是软件使用者。内容包括 API 文档、SDK 文档、安装文档、功能介绍文档、最佳实践、操作指南、常见问题等。

参考目录结构:

docs
├── devel                            # 开发文档,可以提前规划好,英文版文档和中文版文档
│   ├── en-US/                       # 英文版文档,可以根据需要组织文件结构
│   └── zh-CN                        # 中文版文档,可以根据需要组织文件结构
│       └── development.md           # 开发手册,可以说明如何编译、构建、运行项目
├── guide                            # 用户文档
│   ├── en-US/                       # 英文版文档,可以根据需要组织文件结构
│   └── zh-CN                        # 中文版文档,可以根据需要组织文件结构
│       ├── api/                     # API 文档
│       ├── best-practice            # 最佳实践,存放一些比较重要的实践文章
│       │   └── authorization.md
│       ├── faq                      # 常见问题
│       │   ├── iam-apiserver
│       │   └── installation
│       ├── installation             # 安装文档
│       │   └── installation.md
│       ├── introduction/            # 产品介绍文档
│       ├── operation-guide          # 操作指南,可根据 RESTful 资源再划分为更细的子目录,存放系统功能操作手册
│       │   ├── policy.md
│       │   ├── secret.md
│       │   └── user.md
│       ├── quickstart               # 快速入门
│       │   └── quickstart.md
│       ├── README.md                # 用户文档入口文件
│       └── sdk                      # SDK 文档
│           └── golang.md
└── images                           # 图片存放目录
    └── 部署架构v1.png
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# API 文档

一般由后端开发人员编写,描述组件提供的 API 以及调用方法。

可以编写 Word/Markdown 格式文档、借助工具编写(填充内容)、通过注释生成(如 Swagger)等。

通常需要包含完整的 API 接口介绍文档(接口描述、请求方法、请求参数、输出参数和请求示例)、API 接口变更历史文档、通用说明、数据结构说明、错误码描述和 API 接口使用文档。

  • README.md :API 接口介绍文档,会分类介绍 IAM 支持的 API 接口,并会存放相关 API 接口文档的链接,方便开发者查看。
  • CHANGELOG.md :API 接口文档变更历史,方便进行历史回溯,也可以使调用者决定是否进行功能更新和版本更新。
  • generic.md :用来说明通用的请求参数、返回参数、认证方法和请求方法等。
  • struct.md :用来列出接口文档中使用的数据结构。这些数据结构可能被多个 API 接口使用,会在 user.md、secret.md、policy.md 文件中被引用。
  • user.md 、 secret.md 、 policy.md :API 接口文档,相同 REST 资源的接口会存放在一个文件中,以 REST 资源名命名文档名。
  • error_code.md :错误码描述,通过程序自动生成。

其中接口描述:

  • 接口描述:描述接口实现的功能。
  • 请求方法:接口的请求方法,格式为 HTTP 方法 请求路径,比如 POST /v1/users。在 通用说明 中的 请求方法 部分,会说明接口的请求协议和请求地址。
  • 输入参数:接口的输入字段,分为 Header 参数、Query 参数、Body 参数、Path 参数。每个字段通过:参数名称、必选、类型 和 描述 4 个属性来描述。如果参数有限制或者默认值,可在描述部分注明。
  • 输出参数:接口返回字段,每个字段通过 参数名称、类型 和 描述 3 个属性来描述。
  • 请求示例:真实的 API 接口请求和返回示例。

# Swagger

使用 go-swagger 生成文档,可参考代码:gopractise-demo/swagger (opens new window)。

安装 swagger 命令行工具:

go get -u github.com/go-swagger/go-swagger/cmd/swagger
swagger version
# dev
1
2
3

在 Model 层代码中写上 Swagger 注释 sg/api/user.go:

// Package api defines the user model.
package api

// User represents body of User request and response.
type User struct {
    // User's name.
    // Required: true
    Name string `json:"name"`

    // User's nickname.
    // Required: true
    Nickname string `json:"nickname"`

    // User's address.
    Address string `json:"address"`

    // User's email.
    Email string `json:"email"`
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

编写带 go-swagger 注释的 API 文档 sg/docs/doc.go:

// Package docs awesome.
//
// Documentation of our awesome API.
//
//     Schemes: http, https
//     BasePath: /
//     Version: 0.1.0
//     Host: some-url.com
//
//     Consumes:
//     - application/json
//
//     Produces:
//     - application/json
//
//     Security:
//     - basic
//
//    SecurityDefinitions:
//    basic:
//      type: basic
//
// swagger:meta
package docs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

编写 API 定义文件 sg/docs/user.go :

package docs

import (
    "github.com/marmotedu/gopractise-demo/sg/api"
)

// swagger:route POST /users user createUserRequest
// Create a user in memory.
// responses:
//   200: createUserResponse
//   default: errResponse

// swagger:route GET /users/{name} user getUserRequest
// Get a user from memory.
// responses:
//   200: getUserResponse
//   default: errResponse

// swagger:parameters createUserRequest
type userParamsWrapper struct {
    // This text will appear as description of your request body.
    // in:body
    Body api.User
}

// This text will appear as description of your request url path.
// swagger:parameters getUserRequest
type getUserParamsWrapper struct {
    // in:path
    Name string `json:"name"`
}

// This text will appear as description of your response body.
// swagger:response createUserResponse
type createUserResponseWrapper struct {
    // in:body
    Body api.User
}

// This text will appear as description of your response body.
// swagger:response getUserResponse
type getUserResponseWrapper struct {
    // in:body
    Body api.User
}

// This text will appear as description of your error response body.
// swagger:response errResponse
type errResponseWrapper struct {
    // Error code.
    Code int `json:"code"`

    // Error message.
    Message string `json:"message"`
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

在 main.go 文件中导入 docs 包,使 go-swagger 在递归解析 main 包的依赖时找到 docs 包,并解析包中的注释。

import (
    // ...
	// This line is necessary for go-swagger to find your docs!
	_ "github.com/marmotedu/gopractise-demo/sg/docs"
)
1
2
3
4
5

生成 Swagger API 文档,并启动 HTTP 服务,在浏览器查看 Swagger:

swagger generate spec -o swagger.yaml
swagger serve --no-open -F=redoc --port 36666 swagger.yaml
1
2

也可以生成 JSON 格式的 Swagger 文档:

swagger generate spec -i ./swagger.yaml -o ./swagger.json
1

其它功能可参考: Swagger 2.0 (opens new window)。

  • README 文档
  • 项目文档
  • API 文档
  • Swagger