Golang中使用Swagger生成API文档的流程步骤

更新时间：2024年07月25日 09:41:20 作者：小小的木头人

Swagger 是一款强大的 API 文档生成工具,可以帮助开发者轻松创建、管理和展示 RESTful API 文档,在本文中,我们将介绍如何在 Golang 项目中使用 Swagger 来生成 API 文档,文中有相关的代码示例供大家参考,需要的朋友可以参考下

前提条件

Golang 开发环境（推荐使用 Go 1.16 或更高版本）
Go Modules 管理工具
已安装的 Git 工具

第一步：安装 Swagger 工具

在开始之前，我们需要安装 Swagger 工具。你可以使用以下命令来安装 Swagger：

go install github.com/swaggo/swag/cmd/swag@latest

安装完成后，可以通过运行以下命令来验证安装是否成功：

swag --v

第二步：安装 Swaggo 依赖

Swaggo 是一个用于 Golang 的 Swagger 文档生成器。我们需要在项目中安装 Swaggo 依赖：

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

第三步：编写 API 代码

接下来，我们编写一个简单的 API 示例。在项目根目录下创建一个 main.go 文件，并添加以下内容：

package main

import (
    "github.com/gin-gonic/gin"
    "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"
    _ "go-swagger-example/docs"
)

// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8080
// @BasePath /api/v1

func main() {
    r := gin.Default()

    // Simple group: v1
    v1 := r.Group("/api/v1")
    {
        v1.GET("/hello", helloHandler)
    }

    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    r.Run()
}

// helloHandler godoc
// @Summary Show a hello message
// @Description get string message
// @Tags example
// @Accept  json
// @Produce  json
// @Success 200 {string} string "ok"
// @Router /hello [get]
func helloHandler(c *gin.Context) {
    c.JSON(200, gin.H{
        "message": "hello world",
    })
}

第四步：生成 Swagger 文档

在编写好 API 代码后，我们可以使用 Swaggo 生成 Swagger 文档。在项目根目录下运行以下命令：

swag init

运行此命令后，会在项目根目录下生成 docs 文件夹，其中包含生成的 Swagger 文档。

第五步：运行项目并访问 Swagger UI

最后，我们运行项目，并访问 Swagger UI。运行以下命令启动项目：

go run main.go

在浏览器中访问 http://localhost:8080/swagger/index.html，即可看到生成的 Swagger UI 页面，其中包含了我们编写的 API 文档。

以上就是Golang中使用Swagger生成API文档的流程步骤的详细内容，更多关于Golang Swagger生成API文档的资料请关注脚本之家其它相关文章！

您可能感兴趣的文章:

详解如何保留Go程序崩溃现场
这篇文章主要为大家介绍了如何保留Go程序崩溃现场示例详解,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪
2023-12-12
使用Go语言实现跨域资源共享(CORS)设置
在Web开发中,跨域资源共享（CORS）是一种重要的安全机制,它允许许多资源在一个网页上被另一个来源的网页所访问,然而,出于安全考虑,浏览器默认禁止这种跨域访问,为了解决这个问题,我们可以使用Go语言来设置CORS,需要的朋友可以参考下
2024-06-06
使用go实现一个超级mini的消息队列的示例代码
本文主要介绍了使用go实现一个超级mini的消息队列的示例代码，文中通过示例代码介绍的非常详细，具有一定的参考价值，感兴趣的小伙伴们可以参考一下
2021-12-12
教你一分钟配置好Go语言开发环境(多种操作系统)
在这篇文章中,我们从头到尾一步步指导你配置Golang开发环境,并编写你的第一个"Hello, World!"程序,我们详细解释了在多种操作系统（包括Windows、Linux和macOS）下的安装过程、环境变量设置以及如何验证安装是否成功
2023-09-09
Go errors默认加堆栈信息的作用分析
这篇文章主要为大家介绍了Go errors默认加堆栈信息作用分析,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪
2023-12-12
go RWMutex的实现示例
本文主要来介绍读写锁的一种Go语言的实现方式RWMutex，文中通过示例代码介绍的非常详细，具有一定的参考价值，感兴趣的小伙伴们可以参考一下
2022-03-03
goweb原生实现HTTP文件上传功能
在Go语言中,使用原生net/http包实现HTTP文件上传功能,主要依赖multipart/form-data编码解析和文件流处理, 下面就来详细的介绍一下如何实现,感兴趣的可以了解一下
2026-02-02
Go语言Gin框架获取请求参数的两种方式
在添加路由处理函数之后,就可以在路由处理函数中编写业务处理代码了,而编写业务代码第一件事一般就是获取HTTP请求的参数吧,Gin框架在net/http包的基础上封装了获取参数的方式,本文小编给大家介绍了获取参数的两种方式,需要的朋友可以参考下
2024-01-01
Go语言获取文件的名称、前缀、后缀
这篇文章主要介绍了Go语言获取文件的名称、前缀、后缀，具有很好的参考价值，希望对大家有所帮助。一起跟随小编过来看看吧
2021-05-05
go语言中HTTPRouter的算法演进
这篇文章主要从开发中常见的应用场景 “路由管理” 为例，为大家详细介绍一下三种常用的实现方案背后的数据结构和算法，感兴趣的小伙伴可以了解一下
2023-08-08