# 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
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
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
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
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
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
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
2
也可以生成 JSON 格式的 Swagger 文档:
swagger generate spec -i ./swagger.yaml -o ./swagger.json
1
其它功能可参考: Swagger 2.0 (opens new window)。