Go-web如何一步步整合swagger-ui
我们可以官方提供的方式： github.com/go-swagger/… , 主要方式是：1、写我们的go程序，2、让swagger工具扫描我们的go文件，3、生成swagger注释。
我们先说存在的问题：1、注释本地生成，会因为swagger版本不一致出现问题，出现各种git冲突，需要采用打包编译时去执行生成。2、违背了编程的方式。 3、为什么Java的swagger那么火，是因为和spring-boot完美整合，那么Spring解决的其实就是ioc的控制，所以go的web也不需要程序去控制，路由，输入，输出，所以我们需要这么做。
前期准备
1、需要实现Spring-Boot的 controoler接口的方式
大致需求：1、拿到路由，2、拿到请求、响应（这个是go所有web框架做不到的，所以需要转变思想）
@RestController
public class UserController {
@Autowired
private UserRepository repository;
@PostMapping("/save")
public User save(UserInfoDto info) {
return repository.save(User.builder().id(info.getId()).userName(info.getName()).build());
}
}
复制代码
2、转变思想
这个反射调用的框架，我写了一个，希望大家多多提交bug，因为反射本身缺陷很多： github.com/Anthony-Don…
var (
userService = service.NewUserService()
)
func userRoute(e *engines.Engine) {
g := e.Group("/report")
g.POST("benchmark", http.NewHandlerFunc(userService.BenchMark))
}
// 定义 context.Context(必不可少),类似于Java的ThreadLocal
// request *dto.BenchmarkRequest 请求
// *dto.BenchmarkResponse 响应
// error 由于go本身没有throw，所以需要显示的申明
// 后期考虑加入web模块，但是目前主流web框架都是依赖于ctx向下传递，所以go和Java这点不一样(目前不考虑，可以考虑使用gin的context)，虽然Springmvc中也可以接受http-request,http-response 但是由于它的bind，用户都不care了(这就是申明式编程的好处)
type UserService interface {
BenchMark(ctx context.Context, request *dto.BenchmarkRequest) (*dto.BenchmarkResponse, error)
}
复制代码
实现了这个，那么我们就开始吧，因为这些要求的，我们都可以拿到。
3、定义强路由
1、因为go本身并没有方法级别的注解，如果我们可以在每个interface上申明接口，在每个方法上申明路由
// path=/user_service
type UserService interface {
// path=/benchmark method=get
BenchMark(ctx context.Context, request *dto.BenchmarkRequest) (*dto.BenchmarkResponse, cerror.Cerror)
}
复制代码
如果这样子，那么对于go的开发者特别不友好
2、所有采用func注册的方式
可以在接口后面指定get/其他
g.POST("benchmark", http.NewHandlerFunc(userService.BenchMark),op.Get())
复制代码
目前采用的这种方式：1、可以显示的申明，符合go开发者的习惯，2、可以不用扫描go文件（spring-boot采用的这种方式）
整合swagger客户端
找到swagger的web端资源包，然后将其都暴漏出去，接下来核心就是 /swagger.json 了。
资源在我的这个项目的swagger里面 github.com/Anthony-Don… ，后期会考虑静态资源使用api调用的方式(转发的方式)，目前是借助工具写在了go文件里： github.com/a-urth/go-b… ，这个工具很nice，可以讲文件写入到go文件里，以二进制的形式，我们知道go是不可以打包成jar包的，只有二进制文件，静态资源是一个很难受的事情，所以需要这么做。
const (
js = "js"
css = "css"
html = "html"
byte = "byte"
json = "json"
)
func addSwagger(path string, _type string) func(writer http.ResponseWriter, request *http.Request) {
return func(writer http.ResponseWriter, request *http.Request) {
body, _ := swagger.Asset(path)
switch _type {
case js:
writer.Header().Set("content-type", "application/javascript")
case css:
writer.Header().Set("content-type", "text/css")
case json:
writer.Header().Set("content-type", "application/json")
}
if _type == byte {
fmt.Fprint(writer, body)
return
}
fmt.Fprint(writer, string(body))
}
}
func addSwaggerRouter(path string, _type string) {
http.HandleFunc("/"+path, addSwagger(path, _type))
}
func main() {
// swagger内置服务端需要的东西
addSwaggerRouter("swagger-ui/absolute-path.js", js)
addSwaggerRouter("swagger-ui/favicon-16x16.png", byte)
addSwaggerRouter("swagger-ui/favicon-32x32.png", byte)
addSwaggerRouter("swagger-ui/index.html", html)
addSwaggerRouter("swagger-ui/index.js", js)
addSwaggerRouter("swagger-ui/oauth2-redirect.html", html)
addSwaggerRouter("swagger-ui/package.json", json)
addSwaggerRouter("swagger-ui/swagger-ui-bundle.js", js)
addSwaggerRouter("swagger-ui/swagger-ui-bundle.js.map", html)
addSwaggerRouter("swagger-ui/swagger-ui-standalone-preset.js", js)
addSwaggerRouter("swagger-ui/swagger-ui-standalone-preset.js.map", html)
addSwaggerRouter("swagger-ui/swagger-ui.css", css)
addSwaggerRouter("swagger-ui/swagger-ui.css.map", html)
addSwaggerRouter("swagger-ui/swagger-ui.js", js)
addSwaggerRouter("swagger-ui/swagger-ui.js.map", html)
http.HandleFunc("/swagger.json", func(writer http.ResponseWriter, request *http.Request) {
writer.Header().Set("content-type", "application/json")
fmt.Fprintf(writer, doc)
})
http.ListenAndServe(":8888", nil)
}
复制代码
swagger-json
这个文件来自于 faygo，swagger核心是一个api接口，类似于下面这个样子
{
"swagger": "2.0",
"info": {
"description": "Spring Swaager2 REST API",
"version": "V1",
"title": "REST API",
"contact": {
"name": "anthony",
"url": "https://github.com/Anthony-Dong",
"email": "574986060@qq.com"
},
"license": {
"name": "The Apache License",
"url": "https://opensource.org/licenses/MIT"
}
},
"host": "localhost:8888",
"basePath": "/",
"tags": [
{
"name": "user-controller",
"description": "User Controller"
}
],
"paths": {
"/find/{id}": {
"get": {
"tags": [
"user-controller"
],
"summary": "find",
"operationId": "findUsingGET",
"produces": [
"*/*"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "id",
"required": true,
"type": "integer",
"format": "int64"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/User"
}
}
},
"deprecated": false
}
},
"/save/{name}": {
"get": {
"tags": [
"user-controller"
],
"summary": "echo",
"operationId": "echoUsingGET",
"produces": [
"*/*"
],
"parameters": [
{
"name": "name",
"in": "path",
"description": "name",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/User"
}
}
},
"deprecated": false
}
}
},
"definitions": {
"User": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"userName": {
"type": "string"
}
},
"title": "User"
}
}
}
复制代码
一步步写doc
下面是swagger-doc的大致结构，我们必须将我们的api注入进去
doc := swagger.Swagger{
Version: swagger.Version,
Info: &swagger.Info{
Title: "REST API",
Contact: &swagger.Contact{
Email: "fanhaodong516@gmail.com",
},
License: &swagger.License{
Name: "The Apache License",
Url: "https://opensource.org/licenses/MIT",
},
},
Host: "localhost:8888",
BasePath: "/",
Tags: []*swagger.Tag{}, //tag
Paths: map[string]map[string]*swagger.Opera{},// 所有的api路由
Definitions: map[string]*swagger.Definition{},// 定义dto对象
}
复制代码
tag 是什么
user-controller 就是一个tag ，对于go来说一般是group可以定义为一个 controller
// Tag object
Tag struct {
Name string `json:"name"` // 一个标签：user-controller
Description string `json:"description"` // 一个des：user-controller
}
复制代码
同时所有的 path 都可以指定多个 tag
Opera struct {
Tags []string `json:"tags"` // 这里是tag
Summary string `json:"summary"`
Description string `json:"description"`
OperationId string `json:"operationId"`
Consumes []string `json:"consumes,omitempty"`
Produces []string `json:"produces,omitempty"`
Parameters []*Parameter `json:"parameters,omitempty"`
Responses map[string]*Resp `json:"responses"` // {"httpcode":resp}
Security []map[string][]string `json:"security,omitempty"`
}
复制代码
认识path
这就是一个path
Paths map[string]map[string]*Opera `json:"paths,omitempty"` 复制代码
结构是个两级map
"/save": {
"post": {
"tags": [
"user-controller"
],
"summary": "echo",
"operationId": "echoUsingPOST",
"consumes": [ //请求类型
"application/json"
],
"produces": [ // 响应类型
"*/*"
],
"parameters": [ // 核心关注的点 ,如果多级别
{
"name": "id", // 字段描述
"in": "query", // 查询
"required": false, // 是否强需求，可以借助于binding，也就是go的Validator(https://github.com/go-playground/validator)
"type": "integer", // 类型
"format": "int64" // 真实类型(go类型)
},
{
"name": "name",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "user.id",
"in": "query",
"required": false,
"type": "integer",
"format": "int64"
},
{
"name": "user.userName",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {// 状态吗
"description": "OK", // 响应描述
"schema": {
"$ref": "#/definitions/User" // 指定路由：（nice，所以我们的dto全部放到modle里）
}
}
},
"deprecated": false
}
},
复制代码
总结
通过以上，我们可以get到，确实是不是特比难，是有一定规律的，那么接下来，我们就开始设计框架了。
正文到此结束
- 本文标签： java https 开发者 HTML schema ioc tag spring git UI App Service bug struct map 注释 总结 JavaScript validator ip cat 需求 开发 Security id mail description 代码 REST ACE 服务端 编译 find GitHub SpringMVC http 希望 web API list src IO apache js CSS json build ORM
- 版权声明： 本文为互联网转载文章，出处已在文章中说明(部分除外)。如果侵权，请联系本站长删除，谢谢。
- 本文海报： 生成海报一 生成海报二
热门推荐
相关文章
近期评论
-
文章和留言都翻到11页了 没有OOM
-
-
朋友，翻页到11页，及以后，会出现OOM，无法访问
-
-
搞个gitee的项目
-
-
版本号是多少，你可以下载哪个代码仓库，jdk选1.8 直接跑就行
-
-
-
Loading...
![[HBLOG]公众号](https://www.liuhaihua.cn/img/qrcode_gzh.jpg)
