对github项目提PR 请求的保姆级教程——以修改casdoor项目的swagger文档为例，干货满满_在github上提pr

Github入门教程可以在腾讯犀牛鸟开源人才培养计划里面学习。

PR简介

PR(Pull Request) 即拉取请求,是 GitHub 上进行协同开发的一种非常常用的方式。
它的基本流程是：

1. 开发者fork一个开源项目的代码库,将其克隆到本地。
2. 在本地对代码进行修改、添加新功能等。
3. 将本地修改后的代码push到开发者自己的代码库中。
4. 在开源项目的代码库中,发起一个pull request,请求项目维护者将开发者的代码merge到项目主代码库中。
5. 项目维护者review代码,如果没有问题则approve并merge该PR。
6. 开发者的代码就正式成为了该开源项目的一部分。

fork 与clone

接下来按照步骤，逐步进行。
把casdoor的github代码fork到自己的仓库里，通过这种方法，开发者可以在fork后的代码库中进行修改、新增功能，然后通过pull request将代码贡献回原项目。

通过fork，你的仓库里就会多一个项目。

怎样对fork后的代码库进行修改呢？当然得将代码克隆到本地噻！右键点击空白处——你想保存该项目的路径下，用git打开：

然后克隆你的代码库到本地，在git上输入：

git clone https://github.com/此处应该是你的github用户名/casdoor.git
1

此时你会发现该路径下多了一个文件夹，名为casdoor，克隆成功。

修改本地swagger文件（含bee的使用）

如何修改casdoor的swagger文件呢？简单来说就是修改注释代码然后用casbin魔改的bee工具生成swagg.json文件。我们知道，beego框架为生成交换文件提供支持，以便通过称为“bee”的命令行工具清除api。 Casdoor也以beego为基础。 但我们发现bee生成的swagger文件未能将api分类为“@Tag”标签， 我们修改了原bee以执行功能。那么如何写注释呢？

大多数规则与原bee comment格式完全相同， 唯一的差异是api必须按照"@Tag"标签分成不同的组别， 因此，开发者有义务确保正确添加此标签。 下面是一个示例：

// GetLdap
// @Title GetLdap
// @Tag Account API
// @Description get ldap
// @Param	id	query	string	true	"id"
// @Success 200 {object} object.Ldap The Response object
// @router /get-ldap [get]
func (c *ApiController) GetLdap() {
	id := c.Input().Get("id")

	if util.IsStringsEmpty(id) {
		c.ResponseError(c.T("general:Missing parameter"))
		return
	}

	_, name := util.GetOwnerAndNameFromId(id)
	c.ResponseOk(object.GetMaskedLdap(object.GetLdap(name)))
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

具有相同"@Tag"标签的 api 将会被放入同一个组。

我们可以把注释分类：

@Title

接口的标题，用来标示唯一性，唯一，可选

格式：之后跟一个描述字符串

@Description

接口的作用，用来描述接口的用途，唯一，可选

格式：之后跟一个描述字符串

@Param

请求的参数，用来描述接受的参数，多个，可选

格式：变量名 传输类型 类型 是否必须 描述

变量名：字符串

传输类型：path or body or query or form or header

• query 表示带在url串里面?aa=bb&cc=dd

• form 表示使用表单递交数据

• path 表示URL串中得字符，例如/user/{uid} 那么uid就是一个path类型的参数

• body 表示使用raw body进行数据的传输

• header 表示通过header进行数据的传输
  类型：

• string

• int

• int64

• 对象，这个地方大家写的时候需要注意，需要是相对于当前项目的路径.对象，例如models.Object表示models目录下的Object对象，这样bee在生成文档的时候会去扫描改对象并显示给用户改对象。
  是否必须：true 或者false

描述：字符串

@Success

成功返回的code和对象或者信息

格式：code 对象类型 信息或者对象路径

code：表示HTTP的标准status code，200 201等

对象类型：{object}表示对象，其他默认都认为是字符类型，会显示第三个参数给用户，如果是{object}类型，那么就会去扫描改对象，并显示给用户

对象路径和上面Param中得对象类型一样，使用路径.对象的方式来描述

@Failure

错误返回的信息，

格式： code 信息

code:同上Success

错误信息：字符串描述信息

@router

上面已经描述过支持两个参数，第一个是路由，第二个表示支持的HTTP方法。

注释写完后，就要用casbin提供的bee工具生成swagger文档。以下是casdoor官方文档提供的解决办法：

1. 以正确的格式写入 api

2. 获取资源库 https://github.com/casbin/bee

3. build the modified bee, for example, in the root directory of casbin/bee, run

go build -o mybee .
1

4. copy mybee to the base directory of casdoor

5. in that directory, run

mybee generate docs
1

6. 之后你会发现生成新的swagger文件。

以下是对以上步骤的理解与使用：

注释写完后先去https://github.com/casbin/bee获取bee工具，具体过程是将该仓库的代码克隆到本地（你也可以先fork，再克隆，因为不需要修改这个仓库的代码，所以可以不用fork）
在你想保存该bee工具代码的路径处用git bash打开，输入命令：

git clone https://github.com/casbin/bee.git
1

然后进入该项目目录，也就是bee目录，输入命令：

go build -o bee.exe
1

使用该命令，可以在该项目目录下生成bee.exe文件，接下来为了使用它，将它复制一份存放在 $GOPATH/bin 里面，当然你需要把$GOPATH/bin 添加到你的环境变量中，我是将$GOPATH/bin 添加到用户变量的 path中：

至于为什么将bee.exe放在$GOPATH/bin 里面，这似乎是一种规范。配好环境变量后，打开casdoor的项目目录，在终端输入命令：

bee generate docs
1

你会发现，项目中swagger目录里的swagger.json文件和swagger.yml文件均已更新，检查后确认casdoor的swagger文件修改成功。

更新github仓库

由于本地的casdoor项目有文件修改，比如上述的swagger.json文件和swagger.yml文件，接下来就要将他们提交到你的github仓库中。首先输入git status查看本地仓库与远程仓库的文件差异，再输入git add -a将工作目录中的文件添加到暂存区(staging area)，我输入的是 git add swagger，表示只添加swagger这个目录。

然后输入git commit -m "对这次提交的描述"，最后使用git push origin matser将本地的master分支推送到origin远程仓库的master分支。

但是经常会出现这个报错：fatal: unable to access 'https://github.com/uestc-wxy/casdoor.git/': Failed to connect to github.com port 443 after 21065 ms: Couldn't connect to server，或者其他类似于连接的错误，这就需要你在git输入：

git config --global --unset http.proxy 
git config --global --unset https.proxy
1
2

这个bug我已经习以为常了，接下来重新push你的master分支就行了。（万一还是不行，试试换换网络啥的，我当时换成热点突然就push成功了，难绷）

提PR

这时你的github仓库已经更新完成了，下一步就是提PR，打开你要提PR的官方仓库（注意不是你自己fork后的仓库哈），点击pull requests：

再点击New pull request：

然后github会自动比较你的仓库和这个官方仓库代码的差异，符合要求后，可以点击Create pull request。

其实我是通过如下方式提交PR的

fork的仓库代码被修改过后github会出现类似的语句：

点击就能直接进入提PR的界面，符合要求后，就可以点击Create pull request

你提的PR需要标题，你也可以做评论。标题一定要符合规范，否则PR将不予通过。即标题要以属性开头，后面跟上简要描述。

feat: 新功能（feature）
fix: 修补bug
docs: 文档（documentation）
style: 格式（不影响代码运行的变动）
refactor: 重构（即不是新增功能，也不是修改bug的代码变动）
chore: 构建过程或辅助工具的变动
revert: 撤销，版本回退
perf: 性能优化
test：测试
improvement: 改进
build: 打包
ci: 持续集成

比如fix: provide detailed description of ldap in swagger

另外还需要签订CLA协议，提交PR之后你会收到相关邮件，同意该协议即可。

至此，第一次提PR之旅纠结束了，感慨颇多，磕磕绊绊，到处查阅资料，最终也算圆满完成了。