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实际可以不要,其他测试可用):

<meta name="Authorization" id="head_auth" content="" >

body里面的部分内容改成下面代码,主要是添加一个configs配置,直接设置在head里面是没用的,需要设置在SwaggerUIBundle对象里面才有用,最终execute过去的请求是curl:

<script src="https://cdn.bootcss.com/jquery/3.3.1/jquery.min.js"></script>
<script>
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);
} </script>

  

没有设置的时候 验证不通过返回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)

golang学习笔记7 使用beego swagger 实现API自动化文档的更多相关文章

  1. go语言,golang学习笔记4 用beego跑一个web应用

    go语言,golang学习笔记4 用beego跑一个web应用 首页 - beego: 简约 & 强大并存的 Go 应用框架https://beego.me/ 更新的命令是加个 -u 参数,g ...

  2. 用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档

    博客搬到了fresky.github.io - Dawei XU,请各位看官挪步.最新的一篇是:用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档.

  3. spring boot使用swagger生成api接口文档

    前言 在之前的文章中,使用mybatis-plus生成了对应的包,在此基础上,我们针对项目的api接口,添加swagger配置和注解,生成swagger接口文档 具体可以查看本站spring boot ...

  4. MVC-WebApi配置 Swagger(Web Api可视化文档)

    一.从创建MVC WebApi开始 第一步创建MVC WebApi就创建好了,接下来就进入正题,上干货 ================================================ ...

  5. beego 实现API自动化文档

    安装beego和bee工具 1.beego安装 go get -u github.com/astaxie/beego 2.安装bee工具 go get -u github.com/beego/bee ...

  6. .NET Core使用swagger进行API接口文档管理

    一.问题背景 随着技术的发展,现在的开发模式已经更多的转向了前后端分离的模式,在前后端开发的过程中,联系的方式也变成了API接口,但是目前项目中对于API的管理很多时候还是通过手工编写文档,每次的需求 ...

  7. swagger:API在线文档自动生成框架

    传统的API从开发测试开始我们经常借用类似Postman.fiddle等等去做接口测试等等工具:Swagger 为API的在线测试.在线文档提供了一个新的简便的解决方案: NET 使用Swagger ...

  8. SpringBoot18 Swagger、API接口文档生成、WireMock、模拟后台数据

    1 Swagger 1.1 简述 前后端分离的项目需要前后端开发人员协同工作,后台开发人员需要给到前端开发者一套API文档:利用Swagger可以简单高效的帮助后台开发者生成RestfulAPI开发文 ...

  9. MongoDB学习笔记二:创建、更新及删除文档

    插入并保存文档 对目标集使用insert方法插入一个文档: > db.foo.insert({"bar" : "baz"}) 这个操作会给文档增加一个&q ...

随机推荐

  1. 用A标签实现页面内容定位 点击链接跳到具体位置

    经常在维基百科等网站看到目录列表,点击链接会跳到具体的位置,小美眉一直在问是怎么做到的,其实挺简单的,用A标签实现页面内容定位就行了.实例参考微信营销理论手册的目录. 首先用A标签定义目录的链接. & ...

  2. Linux命令实例功能笔记

    ls命令 ls对文件mtime时间进行排序 降序: ls -lt |  grep '^-'    升序:   ls -ltr  |  grep '^-' seq命令 求1000以内所有偶数的和 ech ...

  3. sqlserver生成表结构文档的方法

    只说原理了,具体 可以自己使用程序去生成htm或word文档. 1.首先获取所有的表 SELECT name, id From sysobjects WHERE xtype = 'u' ORDER B ...

  4. Java Script的用途(简介)

    1.可以用来写入HTML输出 <script> document.write("<h1>This is a heading</h1>");//标 ...

  5. Java中的boxing和unboxing(转)

    测试代码: System.out.println(0L == 0);//true System.out.println(((Long)0L).equals(0));//false Integer i1 ...

  6. centos 下python升级

    https://www.cnblogs.com/leon-zyl/p/8422699.html

  7. nodejs 网上下载图片到本地,并判断图片路径是否存在

    var http = require("http"); var fs = require("fs"); var server = http.createServ ...

  8. 安装Cuda9.0+cudnn7.3.1+tensorflow-gpu1.13.1

    我的安装版本: win10 x64 VS2015 conda python 3.7 显卡 GTX 940mx Cuda 9.0 cudnn v7.3.1 Tensorflow-gpu 1.13.1 1 ...

  9. .Net拾忆:从List去除重复-拾忆集合

    方法1: private static List<int> DistinctList(List<int> list) {//去除重复 HashSet<int> ha ...

  10. 题外话:Lua脚本语言存在的意义

    纯属个人见解. 大致来说:c/c++执行效率高,游戏中一些性能敏感的复杂计算需要用c/c++来实现,防止游戏卡顿和低帧率.这些复杂计算包括战斗逻辑,复杂AI,骨骼动画蒙皮骨骼点的坐标计算等等.但c++ ...