Gin 框架: 添加 Swagger UI-阿里云开发者社区

开发者社区> 尹东勋> 正文

Gin 框架: 添加 Swagger UI

简介: 本文将介绍如何在 Gin 框架之上提供 Swagger UI。
+关注继续查看

介绍

本文将介绍如何在 Gin 框架之上提供 Swagger UI。

请访问如下地址获取完整 Gin 教程:

先决条件

Gin 没有自带生成 Swagger UI 配置文件的功能。

我们需要安装 swag 命令行工具来生成 Swagger UI 配置文件。

安装选项 1:通过 RK 命令行
# Install RK CMD
$ go get -u github.com/rookie-ninja/rk/cmd/rk

# Install swag with rk
$ rk install swag
安装选项 2:通过 swag 官网
$ go get github.com/swaggo/swag/cmd/swag

安装 rk-boot

我们介绍 rk-boot 库,用户可以快速搭建基于 Gin 框架的微服务。

go get github.com/rookie-ninja/rk-boot

快速开始

1. 创建 boot.yaml

boot.yaml 文件会告诉 rk-boot 如何启动 Gin 服务,下面的例子中,我们指定了端口,Swagger UI 的 json 文件路径。

---
gin:
  - name: greeter
    port: 8080
    enabled: true
    sw:
      enabled: true
      jsonPath: "docs"
#      path: "sw"        # Default value is "sw", change it as needed
#      headers: []       # Headers that will be set while accessing swagger UI main page.

2. 创建 main.go

为了能让 swag 命令行生成 Swagger UI 参数文件,我们需要在代码中写注释。

详情可参考 swag 官方文档。

package main

import (
    "context"
    "fmt"
    "github.com/gin-gonic/gin"
    "github.com/rookie-ninja/rk-boot"
    "net/http"
)

// @title RK Swagger for Gin
// @version 1.0
// @description This is a greeter service with rk-boot.
func main() {
    // Create a new boot instance.
    boot := rkboot.NewBoot()

    // Register handler
    boot.GetGinEntry("greeter").Router.GET("/v1/greeter", Greeter)

    // Bootstrap
    boot.Bootstrap(context.Background())

    // Wait for shutdown sig
    boot.WaitForShutdownSig(context.Background())
}

// @Summary Greeter service
// @Id 1
// @version 1.0
// @produce application/json
// @Param name query string true "Input name"
// @Success 200 {object} GreeterResponse
// @Router /v1/greeter [get]
func Greeter(ctx *gin.Context) {
    ctx.JSON(http.StatusOK, &GreeterResponse{
        Message: fmt.Sprintf("Hello %s!", ctx.Query("name")),
    })
}

// Response.
type GreeterResponse struct {
    Message string
}

3. 生成 swagger 参数文件

默认会在 docs 文件夹里面创建三个文件。rk-boot 会使用 swagger.json 来初始化 Swagger UI 界面。

$ swag init

$ tree
.
├── boot.yaml
├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── go.mod
├── go.sum
└── main.go

1 directory, 7 files

4. 验证

访问:localhost:8080/sw

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
easyUi 框架中的JS文件传递参数的区别
1.情景一 //JS文件 ajax的请求url : parent.baseUrl+"user/customer/findOne/" + id, //后台JAVA代码接收参数 @RequestMapping(value = "findOne/{id}") @ResponseBody ...
552 0
阿里云服务器端口号设置
阿里云服务器初级使用者可能面临的问题之一. 使用tomcat或者其他服务器软件设置端口号后,比如 一些不是默认的, mysql的 3306, mssql的1433,有时候打不开网页, 原因是没有在ecs安全组去设置这个端口号. 解决: 点击ecs下网络和安全下的安全组 在弹出的安全组中,如果没有就新建安全组,然后点击配置规则 最后如上图点击添加...或快速创建.   have fun!  将编程看作是一门艺术,而不单单是个技术。
4573 0
前端BUI框架表单教程
在开发后台的过程中,前后端需要频繁的通信,后台页面使用BUI模板,后端使用Java开发。 BUI表单使用 BUI提供了4种表单布局,这四种表单布局,我觉得都可以使用 水平表单来替代。
1836 0
iOS开发UI篇—APP主流UI框架结构
iOS开发UI篇—APP主流UI框架结构 一、简单示例 说明:使用APP主流UI框架结构完成简单的界面搭建 搭建页面效果:                                  二、搭建过程和注意点 1.新建一个项目,把原有的控制器删除,添加UITabBarController控制器作为管理控制器 2.对照界面完成搭建 3.注意点: (1)隐藏工具条:配置一个属性,Hideabotton bar在push的时候隐藏底部的bar在那个界面隐藏,就在哪个界面设置。
622 0
+关注
尹东勋
点目科技创始人
64
文章
0
问答
文章排行榜
最热
最新
相关电子书
更多
文娱运维技术
立即下载
《SaaS模式云原生数据仓库应用场景实践》
立即下载
《看见新力量:二》电子书
立即下载