starred/godoxy-yusing
1
0
Fork 0
mirror of https://github.com/yusing/godoxy.git synced 2026-01-11 22:30:47 +01:00
Code Issues 18 Packages Projects Releases 10 Wiki Activity

feat(api): enhance Swagger documentation with detailed API info and update request parameters for uptime

Browse Source
This commit is contained in:
yusing
2025-08-17 16:31:08 +08:00
parent 9931c10fa6
commit 231c0c7665
5 changed files with 123 additions and 180 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
internal/api/handler.go
View File

@@ -21,6 +21,21 @@ import (
"github.com/yusing/go-proxy/internal/auth"
)
// @title GoDoxy API
// @version 1.0
// @description GoDoxy API
// @termsOfService https://github.com/yusing/godoxy/blob/main/LICENSE
// @contact.name Yusing
// @contact.url https://github.com/yusing/godoxy/issues
// @license.name MIT
// @license.url https://github.com/yusing/godoxy/blob/main/LICENSE
// @BasePath /api/v1
// @externalDocs.description GoDoxy Docs
// @externalDocs.url https://docs.godoxy.dev
func NewHandler() *gin.Engine {
gin.SetMode("release")
r := gin.New()

102
internal/api/v1/docs/docs.go
View File

@@ -9,7 +9,15 @@ const docTemplate = `{
"info": {
"description": "{{escape .Description}}",
"title": "{{.Title}}",
"contact": {},
"termsOfService": "https://github.com/yusing/godoxy/blob/main/LICENSE",
"contact": {
"name": "Yusing",
"url": "https://github.com/yusing/godoxy/issues"
},
"license": {
"name": "MIT",
"url": "https://github.com/yusing/godoxy/blob/main/LICENSE"
},
"version": "{{.Version}}"
},
"host": "{{.Host}}",
@@ -629,11 +637,6 @@ const docTemplate = `{
"middleware"
],
"type": "string",
"x-enum-comments": {
"FileTypeConfig": "@name FileTypeConfig",
"FileTypeMiddleware": "@name FileTypeMiddleware",
"FileTypeProvider": "@name FileTypeProvider"
},
"x-enum-varnames": [
"FileTypeConfig",
"FileTypeProvider",
@@ -1240,18 +1243,6 @@ const docTemplate = `{
"sensor_temperature"
],
"type": "string",
"x-enum-comments": {
"SystemInfoAggregateModeCPUAverage": "@name SystemInfoAggregateModeCPUAverage",
"SystemInfoAggregateModeDiskUsage": "@name SystemInfoAggregateModeDiskUsage",
"SystemInfoAggregateModeDisksIOPS": "@name SystemInfoAggregateModeDisksIOPS",
"SystemInfoAggregateModeDisksReadSpeed": "@name SystemInfoAggregateModeDisksReadSpeed",
"SystemInfoAggregateModeDisksWriteSpeed": "@name SystemInfoAggregateModeDisksWriteSpeed",
"SystemInfoAggregateModeMemoryUsage": "@name SystemInfoAggregateModeMemoryUsage",
"SystemInfoAggregateModeMemoryUsagePercent": "@name SystemInfoAggregateModeMemoryUsagePercent",
"SystemInfoAggregateModeNetworkSpeed": "@name SystemInfoAggregateModeNetworkSpeed",
"SystemInfoAggregateModeNetworkTransfer": "@name SystemInfoAggregateModeNetworkTransfer",
"SystemInfoAggregateModeSensorTemperature": "@name SystemInfoAggregateModeSensorTemperature"
},
"x-enum-varnames": [
"SystemInfoAggregateModeCPUAverage",
"SystemInfoAggregateModeMemoryUsage",
@@ -1276,13 +1267,6 @@ const docTemplate = `{
"1mo"
],
"type": "string",
"x-enum-comments": {
"MetricsPeriod15m": "@name MetricsPeriod15m",
"MetricsPeriod1d": "@name MetricsPeriod1d",
"MetricsPeriod1h": "@name MetricsPeriod1h",
"MetricsPeriod1mo": "@name MetricsPeriod1mo",
"MetricsPeriod5m": "@name MetricsPeriod5m"
},
"x-enum-varnames": [
"MetricsPeriod5m",
"MetricsPeriod15m",
@@ -1351,13 +1335,6 @@ const docTemplate = `{
],
"type": "string",
"example": "1m",
"x-enum-comments": {
"MetricsPeriod15m": "@name MetricsPeriod15m",
"MetricsPeriod1d": "@name MetricsPeriod1d",
"MetricsPeriod1h": "@name MetricsPeriod1h",
"MetricsPeriod1mo": "@name MetricsPeriod1mo",
"MetricsPeriod5m": "@name MetricsPeriod5m"
},
"x-enum-varnames": [
"MetricsPeriod5m",
"MetricsPeriod15m",
@@ -1376,13 +1353,15 @@ const docTemplate = `{
},
{
"type": "integer",
"default": 0,
"example": 10,
"name": "limit",
"in": "query"
},
{
"type": "string",
"example": "10",
"type": "integer",
"default": 0,
"example": 10,
"name": "offset",
"in": "query"
}
@@ -1711,14 +1690,16 @@ const docTemplate = `{
"description": "network number",
"type": "array",
"items": {
"type": "integer"
"type": "integer",
"format": "int32"
}
},
"mask": {
"description": "network mask",
"type": "array",
"items": {
"type": "integer"
"type": "integer",
"format": "int32"
}
}
}
@@ -1895,6 +1876,15 @@ const docTemplate = `{
"StateRestarting": "StateRestarting indicates that the container is currently restarting.",
"StateRunning": "StateRunning indicates that the container is running."
},
"x-enum-descriptions": [
"StateCreated indicates the container is created, but not (yet) started.",
"StateRunning indicates that the container is running.",
"StatePaused indicates that the container's current state is paused.",
"StateRestarting indicates that the container is currently restarting.",
"StateRemoving indicates that the container is being removed.",
"StateExited indicates that the container exited.",
"StateDead indicates that the container failed to be deleted. Containers in this state are attempted to be cleaned up when the daemon restarts."
],
"x-enum-varnames": [
"StateCreated",
"StateRunning",
@@ -1973,11 +1963,6 @@ const docTemplate = `{
"provider",
"middleware"
],
"x-enum-comments": {
"FileTypeConfig": "@name FileTypeConfig",
"FileTypeMiddleware": "@name FileTypeMiddleware",
"FileTypeProvider": "@name FileTypeProvider"
},
"x-enum-varnames": [
"FileTypeConfig",
"FileTypeProvider",
@@ -2335,13 +2320,6 @@ const docTemplate = `{
"1d",
"1mo"
],
"x-enum-comments": {
"MetricsPeriod15m": "@name MetricsPeriod15m",
"MetricsPeriod1d": "@name MetricsPeriod1d",
"MetricsPeriod1h": "@name MetricsPeriod1h",
"MetricsPeriod1mo": "@name MetricsPeriod1mo",
"MetricsPeriod5m": "@name MetricsPeriod5m"
},
"x-enum-varnames": [
"MetricsPeriod5m",
"MetricsPeriod15m",
@@ -2848,18 +2826,6 @@ const docTemplate = `{
"network_transfer",
"sensor_temperature"
],
"x-enum-comments": {
"SystemInfoAggregateModeCPUAverage": "@name SystemInfoAggregateModeCPUAverage",
"SystemInfoAggregateModeDiskUsage": "@name SystemInfoAggregateModeDiskUsage",
"SystemInfoAggregateModeDisksIOPS": "@name SystemInfoAggregateModeDisksIOPS",
"SystemInfoAggregateModeDisksReadSpeed": "@name SystemInfoAggregateModeDisksReadSpeed",
"SystemInfoAggregateModeDisksWriteSpeed": "@name SystemInfoAggregateModeDisksWriteSpeed",
"SystemInfoAggregateModeMemoryUsage": "@name SystemInfoAggregateModeMemoryUsage",
"SystemInfoAggregateModeMemoryUsagePercent": "@name SystemInfoAggregateModeMemoryUsagePercent",
"SystemInfoAggregateModeNetworkSpeed": "@name SystemInfoAggregateModeNetworkSpeed",
"SystemInfoAggregateModeNetworkTransfer": "@name SystemInfoAggregateModeNetworkTransfer",
"SystemInfoAggregateModeSensorTemperature": "@name SystemInfoAggregateModeSensorTemperature"
},
"x-enum-varnames": [
"SystemInfoAggregateModeCPUAverage",
"SystemInfoAggregateModeMemoryUsage",
@@ -3074,7 +3040,8 @@ const docTemplate = `{
"icon": {
"type": "array",
"items": {
"type": "integer"
"type": "integer",
"format": "int32"
}
},
"statusCode": {
@@ -3459,6 +3426,7 @@ const docTemplate = `{
},
"time.Duration": {
"type": "integer",
"format": "int64",
"enum": [
-9223372036854775808,
9223372036854775807,
@@ -3499,17 +3467,21 @@ const docTemplate = `{
}
}
}
},
"externalDocs": {
"description": "GoDoxy Docs",
"url": "https://docs.godoxy.dev"
}
}`
// SwaggerInfo holds exported Swagger Info so clients can modify it
var SwaggerInfo = &swag.Spec{
Version: "",
Version: "1.0",
Host: "",
BasePath: "",
BasePath: "/api/v1",
Schemes: []string{},
Title: "",
Description: "",
Title: "GoDoxy API",
Description: "GoDoxy API",
InfoInstanceName: "swagger",
SwaggerTemplate: docTemplate,
LeftDelim: "{{",

98
internal/api/v1/docs/swagger.json
View File

@@ -1,8 +1,20 @@
{
"swagger": "2.0",
"info": {
"contact": {}
"description": "GoDoxy API",
"title": "GoDoxy API",
"termsOfService": "https://github.com/yusing/godoxy/blob/main/LICENSE",
"contact": {
"name": "Yusing",
"url": "https://github.com/yusing/godoxy/issues"
},
"license": {
"name": "MIT",
"url": "https://github.com/yusing/godoxy/blob/main/LICENSE"
},
"version": "1.0"
},
"basePath": "/api/v1",
"paths": {
"/agent/create": {
"post": {
@@ -631,11 +643,6 @@
"middleware"
],
"type": "string",
"x-enum-comments": {
"FileTypeConfig": "@name FileTypeConfig",
"FileTypeMiddleware": "@name FileTypeMiddleware",
"FileTypeProvider": "@name FileTypeProvider"
},
"x-enum-varnames": [
"FileTypeConfig",
"FileTypeProvider",
@@ -1254,18 +1261,6 @@
"sensor_temperature"
],
"type": "string",
"x-enum-comments": {
"SystemInfoAggregateModeCPUAverage": "@name SystemInfoAggregateModeCPUAverage",
"SystemInfoAggregateModeDiskUsage": "@name SystemInfoAggregateModeDiskUsage",
"SystemInfoAggregateModeDisksIOPS": "@name SystemInfoAggregateModeDisksIOPS",
"SystemInfoAggregateModeDisksReadSpeed": "@name SystemInfoAggregateModeDisksReadSpeed",
"SystemInfoAggregateModeDisksWriteSpeed": "@name SystemInfoAggregateModeDisksWriteSpeed",
"SystemInfoAggregateModeMemoryUsage": "@name SystemInfoAggregateModeMemoryUsage",
"SystemInfoAggregateModeMemoryUsagePercent": "@name SystemInfoAggregateModeMemoryUsagePercent",
"SystemInfoAggregateModeNetworkSpeed": "@name SystemInfoAggregateModeNetworkSpeed",
"SystemInfoAggregateModeNetworkTransfer": "@name SystemInfoAggregateModeNetworkTransfer",
"SystemInfoAggregateModeSensorTemperature": "@name SystemInfoAggregateModeSensorTemperature"
},
"x-enum-varnames": [
"SystemInfoAggregateModeCPUAverage",
"SystemInfoAggregateModeMemoryUsage",
@@ -1290,13 +1285,6 @@
"1mo"
],
"type": "string",
"x-enum-comments": {
"MetricsPeriod15m": "@name MetricsPeriod15m",
"MetricsPeriod1d": "@name MetricsPeriod1d",
"MetricsPeriod1h": "@name MetricsPeriod1h",
"MetricsPeriod1mo": "@name MetricsPeriod1mo",
"MetricsPeriod5m": "@name MetricsPeriod5m"
},
"x-enum-varnames": [
"MetricsPeriod5m",
"MetricsPeriod15m",
@@ -1366,13 +1354,6 @@
],
"type": "string",
"example": "1m",
"x-enum-comments": {
"MetricsPeriod15m": "@name MetricsPeriod15m",
"MetricsPeriod1d": "@name MetricsPeriod1d",
"MetricsPeriod1h": "@name MetricsPeriod1h",
"MetricsPeriod1mo": "@name MetricsPeriod1mo",
"MetricsPeriod5m": "@name MetricsPeriod5m"
},
"x-enum-varnames": [
"MetricsPeriod5m",
"MetricsPeriod15m",
@@ -1391,13 +1372,15 @@
},
{
"type": "integer",
"default": 0,
"example": 10,
"name": "limit",
"in": "query"
},
{
"type": "string",
"example": "10",
"type": "integer",
"default": 0,
"example": 10,
"name": "offset",
"in": "query"
}
@@ -1742,7 +1725,8 @@
"description": "network number",
"type": "array",
"items": {
"type": "integer"
"type": "integer",
"format": "int32"
},
"x-nullable": false,
"x-omitempty": false
@@ -1751,7 +1735,8 @@
"description": "network mask",
"type": "array",
"items": {
"type": "integer"
"type": "integer",
"format": "int32"
},
"x-nullable": false,
"x-omitempty": false
@@ -2010,6 +1995,15 @@
"StateRestarting": "StateRestarting indicates that the container is currently restarting.",
"StateRunning": "StateRunning indicates that the container is running."
},
"x-enum-descriptions": [
"StateCreated indicates the container is created, but not (yet) started.",
"StateRunning indicates that the container is running.",
"StatePaused indicates that the container's current state is paused.",
"StateRestarting indicates that the container is currently restarting.",
"StateRemoving indicates that the container is being removed.",
"StateExited indicates that the container exited.",
"StateDead indicates that the container failed to be deleted. Containers in this state are attempted to be cleaned up when the daemon restarts."
],
"x-enum-varnames": [
"StateCreated",
"StateRunning",
@@ -2114,11 +2108,6 @@
"provider",
"middleware"
],
"x-enum-comments": {
"FileTypeConfig": "@name FileTypeConfig",
"FileTypeMiddleware": "@name FileTypeMiddleware",
"FileTypeProvider": "@name FileTypeProvider"
},
"x-enum-varnames": [
"FileTypeConfig",
"FileTypeProvider",
@@ -2636,13 +2625,6 @@
"1d",
"1mo"
],
"x-enum-comments": {
"MetricsPeriod15m": "@name MetricsPeriod15m",
"MetricsPeriod1d": "@name MetricsPeriod1d",
"MetricsPeriod1h": "@name MetricsPeriod1h",
"MetricsPeriod1mo": "@name MetricsPeriod1mo",
"MetricsPeriod5m": "@name MetricsPeriod5m"
},
"x-enum-varnames": [
"MetricsPeriod5m",
"MetricsPeriod15m",
@@ -3357,18 +3339,6 @@
"network_transfer",
"sensor_temperature"
],
"x-enum-comments": {
"SystemInfoAggregateModeCPUAverage": "@name SystemInfoAggregateModeCPUAverage",
"SystemInfoAggregateModeDiskUsage": "@name SystemInfoAggregateModeDiskUsage",
"SystemInfoAggregateModeDisksIOPS": "@name SystemInfoAggregateModeDisksIOPS",
"SystemInfoAggregateModeDisksReadSpeed": "@name SystemInfoAggregateModeDisksReadSpeed",
"SystemInfoAggregateModeDisksWriteSpeed": "@name SystemInfoAggregateModeDisksWriteSpeed",
"SystemInfoAggregateModeMemoryUsage": "@name SystemInfoAggregateModeMemoryUsage",
"SystemInfoAggregateModeMemoryUsagePercent": "@name SystemInfoAggregateModeMemoryUsagePercent",
"SystemInfoAggregateModeNetworkSpeed": "@name SystemInfoAggregateModeNetworkSpeed",
"SystemInfoAggregateModeNetworkTransfer": "@name SystemInfoAggregateModeNetworkTransfer",
"SystemInfoAggregateModeSensorTemperature": "@name SystemInfoAggregateModeSensorTemperature"
},
"x-enum-varnames": [
"SystemInfoAggregateModeCPUAverage",
"SystemInfoAggregateModeMemoryUsage",
@@ -3677,7 +3647,8 @@
"icon": {
"type": "array",
"items": {
"type": "integer"
"type": "integer",
"format": "int32"
},
"x-nullable": false,
"x-omitempty": false
@@ -4220,6 +4191,7 @@
},
"time.Duration": {
"type": "integer",
"format": "int64",
"enum": [
-9223372036854775808,
9223372036854775807,
@@ -4273,5 +4245,9 @@
"x-nullable": false,
"x-omitempty": false
}
},
"externalDocs": {
"description": "GoDoxy Docs",
"url": "https://docs.godoxy.dev"
}
}

84
internal/api/v1/docs/swagger.yaml
View File

@@ -1,3 +1,4 @@
basePath: /api/v1
definitions:
Agent:
properties:
@@ -13,11 +14,13 @@ definitions:
ip:
description: network number
items:
format: int32
type: integer
type: array
mask:
description: network mask
items:
format: int32
type: integer
type: array
type: object
@@ -139,6 +142,15 @@ definitions:
StateRemoving: StateRemoving indicates that the container is being removed.
StateRestarting: StateRestarting indicates that the container is currently restarting.
StateRunning: StateRunning indicates that the container is running.
x-enum-descriptions:
- StateCreated indicates the container is created, but not (yet) started.
- StateRunning indicates that the container is running.
- StatePaused indicates that the container's current state is paused.
- StateRestarting indicates that the container is currently restarting.
- StateRemoving indicates that the container is being removed.
- StateExited indicates that the container exited.
- StateDead indicates that the container failed to be deleted. Containers in this
state are attempted to be cleaned up when the daemon restarts.
x-enum-varnames:
- StateCreated
- StateRunning
@@ -195,10 +207,6 @@ definitions:
- provider
- middleware
type: string
x-enum-comments:
FileTypeConfig: '@name FileTypeConfig'
FileTypeMiddleware: '@name FileTypeMiddleware'
FileTypeProvider: '@name FileTypeProvider'
x-enum-varnames:
- FileTypeConfig
- FileTypeProvider
@@ -436,12 +444,6 @@ definitions:
- 1d
- 1mo
type: string
x-enum-comments:
MetricsPeriod15m: '@name MetricsPeriod15m'
MetricsPeriod1d: '@name MetricsPeriod1d'
MetricsPeriod1h: '@name MetricsPeriod1h'
MetricsPeriod1mo: '@name MetricsPeriod1mo'
MetricsPeriod5m: '@name MetricsPeriod5m'
x-enum-varnames:
- MetricsPeriod5m
- MetricsPeriod15m
@@ -782,17 +784,6 @@ definitions:
- network_transfer
- sensor_temperature
type: string
x-enum-comments:
SystemInfoAggregateModeCPUAverage: '@name SystemInfoAggregateModeCPUAverage'
SystemInfoAggregateModeDiskUsage: '@name SystemInfoAggregateModeDiskUsage'
SystemInfoAggregateModeDisksIOPS: '@name SystemInfoAggregateModeDisksIOPS'
SystemInfoAggregateModeDisksReadSpeed: '@name SystemInfoAggregateModeDisksReadSpeed'
SystemInfoAggregateModeDisksWriteSpeed: '@name SystemInfoAggregateModeDisksWriteSpeed'
SystemInfoAggregateModeMemoryUsage: '@name SystemInfoAggregateModeMemoryUsage'
SystemInfoAggregateModeMemoryUsagePercent: '@name SystemInfoAggregateModeMemoryUsagePercent'
SystemInfoAggregateModeNetworkSpeed: '@name SystemInfoAggregateModeNetworkSpeed'
SystemInfoAggregateModeNetworkTransfer: '@name SystemInfoAggregateModeNetworkTransfer'
SystemInfoAggregateModeSensorTemperature: '@name SystemInfoAggregateModeSensorTemperature'
x-enum-varnames:
- SystemInfoAggregateModeCPUAverage
- SystemInfoAggregateModeMemoryUsage
@@ -954,6 +945,7 @@ definitions:
type: string
icon:
items:
format: int32
type: integer
type: array
statusCode:
@@ -1233,6 +1225,7 @@ definitions:
- 1000000000
- 60000000000
- 3600000000000
format: int64
type: integer
x-enum-varnames:
- minDuration
@@ -1256,8 +1249,20 @@ definitions:
provider:
type: string
type: object
externalDocs:
description: GoDoxy Docs
url: https://docs.godoxy.dev
info:
contact: {}
contact:
name: Yusing
url: https://github.com/yusing/godoxy/issues
description: GoDoxy API
license:
name: MIT
url: https://github.com/yusing/godoxy/blob/main/LICENSE
termsOfService: https://github.com/yusing/godoxy/blob/main/LICENSE
title: GoDoxy API
version: "1.0"
paths:
/agent/create:
post:
@@ -1672,10 +1677,6 @@ paths:
name: type
required: true
type: string
x-enum-comments:
FileTypeConfig: '@name FileTypeConfig'
FileTypeMiddleware: '@name FileTypeMiddleware'
FileTypeProvider: '@name FileTypeProvider'
x-enum-varnames:
- FileTypeConfig
- FileTypeProvider
@@ -2083,17 +2084,6 @@ paths:
in: query
name: aggregate
type: string
x-enum-comments:
SystemInfoAggregateModeCPUAverage: '@name SystemInfoAggregateModeCPUAverage'
SystemInfoAggregateModeDiskUsage: '@name SystemInfoAggregateModeDiskUsage'
SystemInfoAggregateModeDisksIOPS: '@name SystemInfoAggregateModeDisksIOPS'
SystemInfoAggregateModeDisksReadSpeed: '@name SystemInfoAggregateModeDisksReadSpeed'
SystemInfoAggregateModeDisksWriteSpeed: '@name SystemInfoAggregateModeDisksWriteSpeed'
SystemInfoAggregateModeMemoryUsage: '@name SystemInfoAggregateModeMemoryUsage'
SystemInfoAggregateModeMemoryUsagePercent: '@name SystemInfoAggregateModeMemoryUsagePercent'
SystemInfoAggregateModeNetworkSpeed: '@name SystemInfoAggregateModeNetworkSpeed'
SystemInfoAggregateModeNetworkTransfer: '@name SystemInfoAggregateModeNetworkTransfer'
SystemInfoAggregateModeSensorTemperature: '@name SystemInfoAggregateModeSensorTemperature'
x-enum-varnames:
- SystemInfoAggregateModeCPUAverage
- SystemInfoAggregateModeMemoryUsage
@@ -2114,12 +2104,6 @@ paths:
in: query
name: period
type: string
x-enum-comments:
MetricsPeriod15m: '@name MetricsPeriod15m'
MetricsPeriod1d: '@name MetricsPeriod1d'
MetricsPeriod1h: '@name MetricsPeriod1h'
MetricsPeriod1mo: '@name MetricsPeriod1mo'
MetricsPeriod5m: '@name MetricsPeriod5m'
x-enum-varnames:
- MetricsPeriod5m
- MetricsPeriod15m
@@ -2168,12 +2152,6 @@ paths:
in: query
name: interval
type: string
x-enum-comments:
MetricsPeriod15m: '@name MetricsPeriod15m'
MetricsPeriod1d: '@name MetricsPeriod1d'
MetricsPeriod1h: '@name MetricsPeriod1h'
MetricsPeriod1mo: '@name MetricsPeriod1mo'
MetricsPeriod5m: '@name MetricsPeriod5m'
x-enum-varnames:
- MetricsPeriod5m
- MetricsPeriod15m
@@ -2184,14 +2162,16 @@ paths:
in: query
name: keyword
type: string
- example: 10
- default: 0
example: 10
in: query
name: limit
type: integer
- example: "10"
- default: 0
example: 10
in: query
name: offset
type: string
type: integer
produces:
- application/json
responses:

4
internal/api/v1/metrics/upime.go
View File

@@ -7,8 +7,8 @@ import (
)
type UptimeRequest struct {
Limit int `query:"limit" example:"10"`
Offset string `query:"offset" example:"10"`
Limit int `query:"limit" example:"10" default:"0"`
Offset int `query:"offset" example:"10" default:"0"`
Interval period.Filter `query:"interval" example:"1m"`
Keyword string `query:"keyword" example:""`
} // @name UptimeRequest