Gin 集成 Swagger

概述

Swagger 是一款用于生成 RESTful 风格 API 接口文档的框架。目前被大多数框架数框架支持，笔者认为 Swagger 最大的特点就是可以让代码和文档绑定在一起，在开发接口的同时接口文档也做好了。这比文档集中管理要方便的多，可维护性大大提升。让小伙伴更有意愿去写接口文档。

了解 Swagger 基本概念，我们开始切入主题：Gin 集成 Swagger。

安装

前提条件：已安装好 Gin

安装 swagger 文档生成命令行工具。

$ go get -u github.com/swaggo/swag/cmd/swag

生成文档：

$ swag init

安装 gin-swagger

$ go get -u github.com/swaggo/gin-swagger
$ go get -u github.com/swaggo/files

Demo

安装好之后就可以开始啦，为了方便演示，笔者整理了简单Demo。

main.go

package main

import (
	"gin-swag/controllers"
	"github.com/gin-gonic/gin"
	gs "github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
)

// @title Book 接口文档
// @version 1.0
// @description Book 接口文档
// @contact.name roy
// @contact.email roy@mango.im
func main() {
	r := gin.Default()

	// 路由
	r.GET("/books", controllers.FindBooks)
	r.GET("/books/:id", controllers.FindBook)
	r.POST("/books", controllers.CreateBook)
	r.PATCH("/books/:id", controllers.UpdateBook)
	r.DELETE("/books/:id", controllers.DeleteBook)

	r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))
	r.Run()
}

controllers/book.go

package controllers

import (
	_ "gin-swag/docs"
	"github.com/gin-gonic/gin"
	"net/http"
)

type BookInput struct {
	Title  string `json:"title" binding:"required"`
	Author string `json:"author" binding:"required"`
}

// FindBooks 获取书列表
// @Summary 获取书列表
// @Description 获取书列表
// @Tags 书
// @Accept application/json
// @Produce application/json
// @Success 200
// @Router /books [get]
func FindBooks(c *gin.Context) {
	// todo 具体逻辑
	c.JSON(http.StatusOK, gin.H{"data": nil})
}

// FindBook 获取单本书
// @Summary 获取单本书
// @Description 获取单本书
// @Tags 书
// @Accept application/json
// @Produce application/json
// @Param id path int true "book id"
// @Success 200
// @Router /books/{id} [get]
func FindBook(c *gin.Context) {
	// todo 具体逻辑
	c.JSON(http.StatusOK, gin.H{"data": nil})
}

// CreateBook 创建书
// @Summary 创建书
// @Description 创建书
// @Tags 书
// @Accept application/json
// @Produce application/json
// @Param book body BookInput true "book"
// @Success 200
// @Router /books [post]
func CreateBook(c *gin.Context) {
	// todo 具体逻辑
	c.JSON(http.StatusOK, gin.H{"data": nil})
}

// UpdateBook 更新书
// @Summary 更新书
// @Description 更新书
// @Tags 书
// @Accept application/json
// @Produce application/json
// @Param id path int true "book id"
// @Param book body BookInput true "book"
// @Success 200
// @Router /books/{id} [patch]
func UpdateBook(c *gin.Context) {
	// todo 具体逻辑
	c.JSON(http.StatusOK, gin.H{"data": nil})
}

// DeleteBook 删除书
// @Summary 删除书
// @Description 删除书
// @Tags 书
// @Accept application/json
// @Produce application/json
// @Param id path int true "book id"
// @Success 200
// @Router /books/{id} [delete]
func DeleteBook(c *gin.Context) {
	// todo 具体逻辑
	c.JSON(http.StatusOK, gin.H{"data": nil})
}

项目目录下运行 swag init 即可生成文档。

打开 http://localhost:8080/swagger/index.htm

swagger 接口文档

参数解释

注释	描述
description	接口描述信息
id	用于标识操作的唯一字符串。在所有 API 操作中必须是唯一的。
tags	每个 API 操作的标签列表，以逗号分隔。
summary	操作的简短摘要。
accept	API 可以使用的 MIME 类型列表
produce	API 可以生成的 MIME 类型列表。
param	参数用空格分隔
security	每个 API 操作的安全性。
success	以空格分隔的成功响应。
failure	以空格分隔的失败响应。
router	路由

其中 param 支持：

object (struct)
string (string)
integer (int, uint, uint32, uint64)
number (float32)
boolean (bool)
array

更多属性定义参考官方文档：https://swaggo.github.io/swaggo.io/declarative_comments_format/api_operation.html

参考

https://github.com/swaggo/gin-swagger