对github项目提PR 请求的保姆级教程——以修改casdoor项目的swagger文档为例，干货满满
PR简介
PR(Pull Request) 即拉取请求,是 GitHub 上进行协同开发的一种非常常用的方式。
它的基本流程是：
- 开发者fork一个开源项目的代码库,将其克隆到本地。
- 在本地对代码进行修改、添加新功能等。
- 将本地修改后的代码push到开发者自己的代码库中。
- 在开源项目的代码库中,发起一个pull request,请求项目维护者将开发者的代码merge到项目主代码库中。
- 项目维护者review代码,如果没有问题则approve并merge该PR。
- 开发者的代码就正式成为了该开源项目的一部分。
fork 与clone
接下来按照步骤，逐步进行。
把casdoor的github代码fork到自己的仓库里，通过这种方法，开发者可以在fork后的代码库中进行修改、新增功能，然后通过pull request将代码贡献回原项目。
通过fork，你的仓库里就会多一个项目。
怎样对fork后的代码库进行修改呢？当然得将代码克隆到本地噻！右键点击空白处——你想保存该项目的路径下，用git打开：
然后克隆你的代码库到本地，在git上输入：
git clone https://github.com/此处应该是你的github用户名/casdoor.git
此时你会发现该路径下多了一个文件夹，名为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)))
}
具有相同"@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官方文档提供的解决办法：
-
以正确的格式写入 api
-
获取资源库 https://github.com/casbin/bee
-
build the modified bee, for example, in the root directory of casbin/bee, run
go build -o mybee .
-
copy mybee to the base directory of casdoor
-
in that directory, run
mybee generate docs
- 之后你会发现生成新的swagger文件。
以下是对以上步骤的理解与使用：
注释写完后先去https://github.com/casbin/bee获取bee工具，具体过程是将该仓库的代码克隆到本地（你也可以先fork，再克隆，因为不需要修改这个仓库的代码，所以可以不用fork）
在你想保存该bee工具代码的路径处用git bash打开，输入命令：
git clone https://github.com/casbin/bee.git
然后进入该项目目录，也就是bee目录，输入命令：
go build -o bee.exe
使用该命令，可以在该项目目录下生成bee.exe文件，接下来为了使用它，将它复制一份存放在 $GOPATH/bin 里面，当然你需要把$GOPATH/bin 添加到你的环境变量中，我是将$GOPATH/bin 添加到用户变量的 path中：
至于为什么将bee.exe放在$GOPATH/bin 里面，这似乎是一种规范。配好环境变量后，打开casdoor的项目目录，在终端输入命令：
bee generate docs
你会发现，项目中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
这个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之旅纠结束了，感慨颇多，磕磕绊绊，到处查阅资料，最终也算圆满完成了。