Go-Gin-Example项目Swagger接口文档详解-优快云博客

Go-Gin-Example项目Swagger接口文档详解

go-gin-example An example of gin 项目地址: https://gitcode.com/gh_mirrors/go/go-gin-example

项目概述

Go-Gin-Example是一个基于Gin框架构建的RESTful API示例项目，它展示了如何使用Golang开发一个完整的Web服务。该项目实现了文章和标签的管理功能，包括增删改查等基本操作，并提供了Swagger文档支持。

Swagger文档结构解析

基本信息

{
    "swagger": "2.0",
    "info": {
        "description": "An example of gin",
        "title": "Golang Gin API",
        "version": "1.0"
    }
}

这部分定义了API的基本信息：

使用Swagger 2.0规范
项目描述为Gin框架的示例
API标题为"Golang Gin API"
当前版本为1.0

文章管理接口

获取文章列表

"/api/v1/articles": {
    "get": {
        "summary": "Get multiple articles",
        "parameters": [
            {
                "description": "TagID",
                "name": "tag_id",
                "in": "body",
                "schema": {
                    "type": "integer"
                }
            },
            // 其他参数...
        ]
    }
}

此接口支持通过以下条件筛选文章：

tag_id：按标签ID筛选
state：按状态筛选
created_by：按创建人筛选

创建新文章

"post": {
    "summary": "Add article",
    "parameters": [
        {
            "description": "TagID",
            "name": "tag_id",
            "in": "body",
            "required": true
        },
        // 其他必填参数...
    ]
}

创建文章需要提供以下必填字段：

tag_id：关联标签ID
title：文章标题
desc：文章描述
content：文章内容
created_by：创建人
state：文章状态

单篇文章操作

"/api/v1/articles/{id}": {
    "get": {
        "summary": "Get a single article"
    },
    "put": {
        "summary": "Update article"
    },
    "delete": {
        "summary": "Delete article"
    }
}

针对单篇文章提供了完整的CRUD操作：

GET：获取指定ID的文章详情
PUT：更新文章信息
DELETE：删除文章

标签管理接口

获取标签列表

"/api/v1/tags": {
    "get": {
        "summary": "Get multiple article tags",
        "parameters": [
            {
                "name": "name",
                "in": "query"
            },
            {
                "name": "state",
                "in": "query"
            }
        ]
    }
}

支持通过以下查询参数筛选标签：

name：按标签名称模糊查询
state：按状态筛选

标签导入导出

"/api/v1/tags/export": {
    "post": {
        "summary": "Export article tag"
    }
},
"/api/v1/tags/import": {
    "post": {
        "summary": "Import Image",
        "parameters": [
            {
                "type": "file",
                "name": "image",
                "required": true
            }
        ]
    }
}

提供了标签的导入导出功能：

导出：将标签数据导出
导入：通过上传图片文件导入标签数据

认证接口

"/auth": {
    "get": {
        "summary": "Get Auth",
        "parameters": [
            {
                "name": "username",
                "in": "query"
            }
        ]
    }
}

提供基本的认证功能，通过用户名获取认证信息。