526互联

Swagger

发布时间 2023-12-25 14:44:37作者: 看一百次夜空里的深蓝

Swagger 是一组规范和工具，用于设计、构建、文档化和消费 RESTful 风格的 Web 服务。它旨在帮助开发者更轻松地设计和使用 API。

主要组成部分：

  1. OpenAPI 规范（以前称为 Swagger 规范）： 定义了 API 的结构和功能，包括端点、参数、请求和响应格式等。使用 YAML 或 JSON 格式编写，描述了整个 API 的元数据。

  2. Swagger Editor： 提供了一个交互式的编辑器，用于创建和编辑 OpenAPI 规范。

  3. Swagger UI： 一个交互式的用户界面，用于可视化和交互式测试 API。通过 OpenAPI 规范生成交互式文档，开发者可以通过 Swagger UI 浏览 API 的端点、参数和响应，甚至可以在其中进行测试。

  4. Swagger Codegen： 根据 OpenAPI 规范自动生成 API 客户端库、服务器端框架和文档。

优势和功能：

  • 文档化和可视化： 自动生成可交互的 API 文档，开发者可以直观地了解 API 的端点、参数和用法。

  • 代码自动生成： 基于规范，自动生成客户端和服务器端代码，减少了开发工作量和潜在的错误。

  • 易于测试和调试： Swagger UI 提供了一个交互式的界面，可以直接在其中测试 API，方便调试和验证功能。

  • 标准化API设计： 规范的使用有助于标准化和约定 API 设计，使不同团队和开发者更容易理解和集成。

  • 社区和生态系统支持： 拥有庞大的开发者社区和生态系统支持，使得整个工具集不断演进和改进。

Swagger 提供了一整套工具，帮助开发者更轻松地设计、构建和使用 API。它有助于提高 API 的可理解性、可靠性，并能够更好地支持不同团队之间的协作。

 

 1 gin-swagger  嵌入到Gin框架中，通过注释的方式自动生成swagger.json文档
 2 # 1. 源码下载
 3 go get -u github.com/swaggo/swag/cmd/swag
 4 # 2. 安装
 5 go install github.com/swaggo/swag/cmd/swag@latest
 6 # 3.初始化（安装好了就可以用了，每次修改api注释就得重新初始化就会重新生成文档）
 7 swag init
 8 # 4.安装可视化web包
 9 go get -u github.com/swaggo/gin-swagger
10 go get -u github.com/swaggo/files
11 # 5.可以直接开始用拉
12 package main
13 
14 import (
15    "github.com/gin-gonic/gin"
16    docs "github.com/go-project-name/docs"
17    swaggerfiles "github.com/swaggo/files"
18    ginSwagger "github.com/swaggo/gin-swagger"
19    "net/http"
20 )
21 // @BasePath /api/v1
22 
23 // PingExample godoc
24 // @Summary ping example
25 // @Schemes
26 // @Description do ping
27 // @Tags example
28 // @Accept json
29 // @Produce json
30 // @Success 200 {string} Helloworld
31 // @Router /example/helloworld [get]
32 func Helloworld(g *gin.Context)  {
33    g.JSON(http.StatusOK,"helloworld")
34 }
35 
36 func main()  {
37    r := gin.Default()
38    docs.SwaggerInfo.BasePath = "/api/v1"
39    v1 := r.Group("/api/v1")
40    {
41       eg := v1.Group("/example")
42       {
43          eg.GET("/helloworld",Helloworld)
44       }
45    }
46    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
47    r.Run(":8080")
48 
49 }