golang学习笔记7 使用beego swagger 实现API自动化文档

kinila

　　golang学习笔记7 使用beego swagger 实现API自动化文档
　　API 自动化文档 - beego: 简约 & 强大并存的 Go 应用框架
　　https://beego.me/docs/advantage/docs.md
　　使用beego开发api server 和前端拆分开发，使用swagger自动化生成API文档
　　Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。
　　项目地址是：http://swagger.io/
　　使用 beego 开发自带集成了 swagger的东西。
　　https://beego.me/docs/advantage/docs.md
　　github 地址：
　　https://github.com/beego/swagger
　　到项目目录下执行命令：
　　bee run -gendoc=true -downdoc=true
　　会自动下载最新的 swagger 压缩文件
　　启动成功，直接访问
　　http://localhost:8080/swagger/
　　会出来两个url，http://localhost:8080/swagger/swagger.json
　　http://localhost:8080/swagger/swagger.yml

• 第一开启应用内文档开关，在配置文件中设置：EnableDocs = true,
  
• 然后在你的 main.go 函数中引入 _ "beeapi/docs"（beego 1.7.0 之后版本不需要添加该引用）。
  
• 这样你就已经内置了 docs 在你的 API 应用中，然后你就使用 bee run -gendoc=true -downdoc=true,让我们的 API 应用跑起来，
  
• -gendoc=true 表示每次自动化的 build 文档，-downdoc=true 就会自动的下载 swagger 文档查看器
  

　　到 https://github.com/swagger-api/swagger-ui 下载zip包，
　　解压后把dist文件夹复制到swagger目录下即可访问里面的index.html
　　为了方便把文件夹改名成show，把index.html 的url改成本地的
　　//url: "http://petstore.swagger.io/v2/swagger.json",
　　url:"http://localhost:8080/swagger/swagger.json",
　　在浏览器访问
　　http://localhost:8080/swagger/show/index.html
　　即可看到自己项目的api文档了，示例如下：

　　注：如果直接在文件夹打开dist下的index会报跨域的错误

　　注：bee pack时swagger 的他会自动解压文件到swagger目录下，不需要自己再放个目录了，可以把之前的show目录删掉了

添加auth token的方法，需要改造swagger的index.html
　　网上很多方法都是行不通的，在下面这个才找到可行的方法
　　Add JWT authorization header in Swagger v3 · Issue #2915 · swagger-api/swagger-ui · GitHub
　　https://github.com/swagger-api/swagger-ui/issues/2915
　　head 里面添加meta（这个swagger实际可以不要，其他测试可用）：
　　
　　body里面的部分内容改成下面代码，主要是添加一个configs配置，直接设置在head里面是没用的，需要设置在SwaggerUIBundle对象里面才有用，最终execute过去的请求是curl：
　　

　　

　　
window.onload = function() {
　　
// Build a system
　　
const ui = SwaggerUIBundle({
　　
url: "swagger.json",
　　
dom_id: '#swagger-ui',
　　
configs: {
　　
preFetch: function(req) {
　　
if (authToken) {
　　
req.headers["Authorization"] = authToken;
　　
}
　　
return req;
　　
}
　　
},
　　
presets: [
　　
SwaggerUIBundle.presets.apis,
　　
SwaggerUIStandalonePreset
　　
],
　　
plugins: [
　　
SwaggerUIBundle.plugins.DownloadUrl
　　
],
　　
layout: "StandaloneLayout"
　　
})
　　

　　
window.ui = ui
　　
}
　　

　　
var authToken = "";
　　
function addApiKeyAuthorization(){
　　
var key = encodeURIComponent(document.getElementById('input_apiKey').value);
　　
authToken = "Bearer " + key;
　　
//设置请求报文头
　　
//var c1 = $("#head_auth").attr('content');
　　
//console.log("c1 " + c1);
　　
$("#head_auth").attr('content',authToken);
　　
}
　　

　　

　　

　　

　　没有设置的时候 验证不通过返回400错误信息

　　跨域的问题，可以在入口main方法里面加个过滤器filter，允许所有请求都跨域
　　beego/cors.go at master · astaxie/beego · GitHub
　　https://github.com/astaxie/beego/blob/master/plugins/cors/cors.go#L23
　　

// Package cors provides handlers to enable CORS support.　　
// Usage
　　
//import (
　　
// "github.com/astaxie/beego"
　　
//"github.com/astaxie/beego/plugins/cors"
　　
// )
　　
//
　　
//func main() {
　　
//// CORS for https://foo.* origins, allowing:
　　
//// - PUT and PATCH methods
　　
//// - Origin header
　　
//// - Credentials share
　　
//beego.InsertFilter("*", beego.BeforeRouter, cors.Allow(&cors.Options{
　　
//AllowOrigins:     []string{"https://*.foo.com"},
　　
//AllowMethods:     []string{"PUT", "PATCH"},
　　
//AllowHeaders:     []string{"Origin"},
　　
//ExposeHeaders:    []string{"Content-Length"},
　　
//AllowCredentials: true,
　　
//}))
　　
//beego.Run()
　　
//}
　　

　　

　　或者单个 API 增加 CORS 支持
　　c.Ctx.Output.Header("Access-Control-Allow-Origin", "*")
　　另外https的无法访问http的，这个是协议限制的
　　要方便测试可以把所有都设置成通配符*
　　

beego.InsertFilter("*", beego.BeforeRouter, cors.Allow(&cors.Options{　　
AllowOrigins:     []string{"*"},
　　
AllowMethods:     []string{"*"},
　　
AllowHeaders:     []string{"*"},
　　
ExposeHeaders:    []string{"*"},
　　
AllowCredentials: true,
　　
}))
　　

　　

　　---------------------------

QQ群：golang beego技术交流群(316397059)