Go2025/backend
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Feat: add swagger notes

Browse Source
This commit is contained in:
Yi-Ting Shih
2025-12-07 05:19:10 +08:00
parent 56e83b0725
commit 9c30bc009d
11 changed files with 775 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
docs/docs.go
View File

@@ -19,13 +19,51 @@ const docTemplate = `{
"host": "{{.Host}}", "host": "{{.Host}}",
"basePath": "{{.BasePath}}", "basePath": "{{.BasePath}}",
"paths": { "paths": {
"/api/images": { "/api/alias-update": {
"get": { "get": {
"description": "get update notification using websocket",
"summary": "Get notification when alias update",
"responses": {}
}
},
"/api/alias/{id}": {
"delete": {
"description": "delete alias along with the links",
"summary": "Delete alias",
"parameters": [
{
"type": "integer",
"description": "Alias Id",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK"
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Not Found"
}
}
}
},
"/api/aliases": {
"get": {
"description": "get alias ids and names",
"summary": "Get aliases",
"responses": { "responses": {
"200": { "200": {
"description": "OK", "description": "OK",
"schema": { "schema": {
"$ref": "#/definitions/api.getImagesOutputImage" "type": "array",
"items": {
"$ref": "#/definitions/api.getAliasesOutputAlias"
}
} }
}, },
"400": { "400": {
@@ -36,9 +74,177 @@ const docTemplate = `{
} }
} }
} }
},
"/api/image": {
"post": {
"consumes": [
"image/png",
"image/jpeg",
"image/gif"
],
"parameters": [
{
"type": "string",
"description": "userinfo from /auth/gen-login-url",
"name": "userinfo",
"in": "header",
"required": true
}
],
"responses": {
"200": {
"description": "OK"
},
"401": {
"description": "Unauthorized"
}
}
}
},
"/api/image/{id}": {
"delete": {
"description": "delete image along with the links",
"summary": "Delete image",
"parameters": [
{
"type": "integer",
"description": "Image Id",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK"
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Not Found"
}
}
}
},
"/api/image/{id}/aliases": {
"put": {
"parameters": [
{
"type": "integer",
"description": "Image Id",
"name": "id",
"in": "path",
"required": true
},
{
"description": "Payload",
"name": "payload",
"in": "body",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "OK"
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Not Found"
}
}
}
},
"/api/images": {
"get": {
"parameters": [
{
"type": "array",
"items": {
"type": "integer"
},
"collectionFormat": "csv",
"description": "Image Ids",
"name": "images",
"in": "query"
},
{
"type": "array",
"items": {
"type": "integer"
},
"collectionFormat": "csv",
"description": "Alias Ids",
"name": "aliases",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/api.getImagesOutputImage"
}
}
},
"400": {
"description": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
}
}
},
"/auth/gen-login-url": {
"post": {
"parameters": [
{
"description": "Payload",
"name": "payload",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/auth.postGenLoginUrlInput"
}
}
],
"responses": {
"200": {
"description": "Payload",
"schema": {
"$ref": "#/definitions/auth.postGenLoginUrlOutput"
}
},
"400": {
"description": "Bad Request"
}
}
}
} }
}, },
"definitions": { "definitions": {
"api.getAliasesOutputAlias": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
}
},
"api.getImagesOutputImage": { "api.getImagesOutputImage": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -51,10 +257,26 @@ const docTemplate = `{
"id": { "id": {
"type": "integer" "type": "integer"
}, },
"uploaded_at": { "uploadedAt": {
"type": "integer" "type": "integer"
}, },
"uploaded_user_id": { "uploadedUserId": {
"type": "string"
}
}
},
"auth.postGenLoginUrlInput": {
"type": "object",
"properties": {
"userId": {
"type": "string"
}
}
},
"auth.postGenLoginUrlOutput": {
"type": "object",
"properties": {
"loginUrl": {
"type": "string" "type": "string"
} }
} }

230
docs/swagger.json
View File

@@ -11,13 +11,51 @@
}, },
"basePath": "/", "basePath": "/",
"paths": { "paths": {
"/api/images": { "/api/alias-update": {
"get": { "get": {
"description": "get update notification using websocket",
"summary": "Get notification when alias update",
"responses": {}
}
},
"/api/alias/{id}": {
"delete": {
"description": "delete alias along with the links",
"summary": "Delete alias",
"parameters": [
{
"type": "integer",
"description": "Alias Id",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK"
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Not Found"
}
}
}
},
"/api/aliases": {
"get": {
"description": "get alias ids and names",
"summary": "Get aliases",
"responses": { "responses": {
"200": { "200": {
"description": "OK", "description": "OK",
"schema": { "schema": {
"$ref": "#/definitions/api.getImagesOutputImage" "type": "array",
"items": {
"$ref": "#/definitions/api.getAliasesOutputAlias"
}
} }
}, },
"400": { "400": {
@@ -28,9 +66,177 @@
} }
} }
} }
},
"/api/image": {
"post": {
"consumes": [
"image/png",
"image/jpeg",
"image/gif"
],
"parameters": [
{
"type": "string",
"description": "userinfo from /auth/gen-login-url",
"name": "userinfo",
"in": "header",
"required": true
}
],
"responses": {
"200": {
"description": "OK"
},
"401": {
"description": "Unauthorized"
}
}
}
},
"/api/image/{id}": {
"delete": {
"description": "delete image along with the links",
"summary": "Delete image",
"parameters": [
{
"type": "integer",
"description": "Image Id",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK"
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Not Found"
}
}
}
},
"/api/image/{id}/aliases": {
"put": {
"parameters": [
{
"type": "integer",
"description": "Image Id",
"name": "id",
"in": "path",
"required": true
},
{
"description": "Payload",
"name": "payload",
"in": "body",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "OK"
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Not Found"
}
}
}
},
"/api/images": {
"get": {
"parameters": [
{
"type": "array",
"items": {
"type": "integer"
},
"collectionFormat": "csv",
"description": "Image Ids",
"name": "images",
"in": "query"
},
{
"type": "array",
"items": {
"type": "integer"
},
"collectionFormat": "csv",
"description": "Alias Ids",
"name": "aliases",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/api.getImagesOutputImage"
}
}
},
"400": {
"description": "Bad Request"
},
"401": {
"description": "Unauthorized"
}
}
}
},
"/auth/gen-login-url": {
"post": {
"parameters": [
{
"description": "Payload",
"name": "payload",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/auth.postGenLoginUrlInput"
}
}
],
"responses": {
"200": {
"description": "Payload",
"schema": {
"$ref": "#/definitions/auth.postGenLoginUrlOutput"
}
},
"400": {
"description": "Bad Request"
}
}
}
} }
}, },
"definitions": { "definitions": {
"api.getAliasesOutputAlias": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
}
},
"api.getImagesOutputImage": { "api.getImagesOutputImage": {
"type": "object", "type": "object",
"properties": { "properties": {
@@ -43,10 +249,26 @@
"id": { "id": {
"type": "integer" "type": "integer"
}, },
"uploaded_at": { "uploadedAt": {
"type": "integer" "type": "integer"
}, },
"uploaded_user_id": { "uploadedUserId": {
"type": "string"
}
}
},
"auth.postGenLoginUrlInput": {
"type": "object",
"properties": {
"userId": {
"type": "string"
}
}
},
"auth.postGenLoginUrlOutput": {
"type": "object",
"properties": {
"loginUrl": {
"type": "string" "type": "string"
} }
} }

152
docs/swagger.yaml
View File

@@ -1,5 +1,12 @@
basePath: / basePath: /
definitions: definitions:
api.getAliasesOutputAlias:
properties:
id:
type: integer
name:
type: string
type: object
api.getImagesOutputImage: api.getImagesOutputImage:
properties: properties:
aliases: aliases:
@@ -8,9 +15,19 @@ definitions:
type: array type: array
id: id:
type: integer type: integer
uploaded_at: uploadedAt:
type: integer type: integer
uploaded_user_id: uploadedUserId:
type: string
type: object
auth.postGenLoginUrlInput:
properties:
userId:
type: string
type: object
auth.postGenLoginUrlOutput:
properties:
loginUrl:
type: string type: string
type: object type: object
info: info:
@@ -21,15 +38,142 @@ info:
title: Golang 2025 Final Project title: Golang 2025 Final Project
version: 0.0.1 version: 0.0.1
paths: paths:
/api/images: /api/alias-update:
get: get:
description: get update notification using websocket
responses: {}
summary: Get notification when alias update
/api/alias/{id}:
delete:
description: delete alias along with the links
parameters:
- description: Alias Id
in: path
name: id
required: true
type: integer
responses:
"200":
description: OK
"401":
description: Unauthorized
"404":
description: Not Found
summary: Delete alias
/api/aliases:
get:
description: get alias ids and names
responses: responses:
"200": "200":
description: OK description: OK
schema: schema:
$ref: '#/definitions/api.getImagesOutputImage' items:
$ref: '#/definitions/api.getAliasesOutputAlias'
type: array
"400": "400":
description: Bad Request description: Bad Request
"401": "401":
description: Unauthorized description: Unauthorized
summary: Get aliases
/api/image:
post:
consumes:
- image/png
- image/jpeg
- image/gif
parameters:
- description: userinfo from /auth/gen-login-url
in: header
name: userinfo
required: true
type: string
responses:
"200":
description: OK
"401":
description: Unauthorized
/api/image/{id}:
delete:
description: delete image along with the links
parameters:
- description: Image Id
in: path
name: id
required: true
type: integer
responses:
"200":
description: OK
"401":
description: Unauthorized
"404":
description: Not Found
summary: Delete image
/api/image/{id}/aliases:
put:
parameters:
- description: Image Id
in: path
name: id
required: true
type: integer
- description: Payload
in: body
name: payload
required: true
schema:
items:
type: string
type: array
responses:
"200":
description: OK
"401":
description: Unauthorized
"404":
description: Not Found
/api/images:
get:
parameters:
- collectionFormat: csv
description: Image Ids
in: query
items:
type: integer
name: images
type: array
- collectionFormat: csv
description: Alias Ids
in: query
items:
type: integer
name: aliases
type: array
responses:
"200":
description: OK
schema:
items:
$ref: '#/definitions/api.getImagesOutputImage'
type: array
"400":
description: Bad Request
"401":
description: Unauthorized
/auth/gen-login-url:
post:
parameters:
- description: Payload
in: body
name: payload
required: true
schema:
$ref: '#/definitions/auth.postGenLoginUrlInput'
responses:
"200":
description: Payload
schema:
$ref: '#/definitions/auth.postGenLoginUrlOutput'
"400":
description: Bad Request
swagger: "2.0" swagger: "2.0"

23
handlers/api/deleteAlias.go Normal file
View File

@@ -0,0 +1,23 @@
package api
import (
"net/http"
"gitea.konchin.com/go2025/backend/utils"
"github.com/uptrace/bunrouter"
)
// DeleteAlias
//
// @summary Delete alias
// @description delete alias along with the links
// @param id path int64 true "Alias Id"
// @success 200
// @failure 401
// @failure 404
// @router /api/alias/{id} [delete]
func (self *Handlers) DeleteAlias(
w http.ResponseWriter, req bunrouter.Request,
) error {
return utils.Success(w)
}

23
handlers/api/deleteImage.go Normal file
View File

@@ -0,0 +1,23 @@
package api
import (
"net/http"
"gitea.konchin.com/go2025/backend/utils"
"github.com/uptrace/bunrouter"
)
// DeleteImage
//
// @summary Delete image
// @description delete image along with the links
// @param id path int64 true "Image Id"
// @success 200
// @failure 401
// @failure 404
// @router /api/image/{id} [delete]
func (self *Handlers) DeleteImage(
w http.ResponseWriter, req bunrouter.Request,
) error {
return utils.Success(w)
}

19
handlers/api/getAliasUpdate.go Normal file
View File

@@ -0,0 +1,19 @@
package api
import (
"net/http"
"gitea.konchin.com/go2025/backend/utils"
"github.com/uptrace/bunrouter"
)
// GetAliasUpdate
//
// @summary Get notification when alias update
// @description get update notification using websocket
// @router /api/alias-update [get]
func (self *Handlers) GetAliasUpdate(
w http.ResponseWriter, req bunrouter.Request,
) error {
return utils.Success(w)
}

30
handlers/api/getAliases.go Normal file
View File

@@ -0,0 +1,30 @@
package api
import (
"fmt"
"net/http"
"github.com/uptrace/bunrouter"
)
type getAliasesOutputAlias struct {
Id int64 `json:"id"`
Name string `json:"name"`
}
// GetAliases
//
// @summary Get aliases
// @description get alias ids and names
// @success 200 {object} []getAliasesOutputAlias
// @failure 400
// @failure 401
// @router /api/aliases [get]
func (self *Handlers) GetAliases(
w http.ResponseWriter, req bunrouter.Request,
) error {
// mock output
fmt.Fprintf(w, "%s", `[{"id": 1, "name": "yajiu"}]`)
return nil
// return utils.Success(w)
}

8
handlers/api/getImages.go
View File

@@ -9,14 +9,16 @@ import (
type getImagesOutputImage struct { type getImagesOutputImage struct {
Id int64 `json:"id"` Id int64 `json:"id"`
Uploader string `json:"uploaded_user_id"` Uploader string `json:"uploadedUserId"`
UploadTS int64 `json:"uploaded_at"` UploadTS int64 `json:"uploadedAt"`
Aliases []string `json:"aliases"` Aliases []string `json:"aliases"`
} }
// GetImages // GetImages
// //
// @success 200 {object} getImagesOutputImage // @param images query []int64 false "Image Ids" attribute(optional)
// @param aliases query []int64 false "Alias Ids" attribute(optional)
// @success 200 {object} []getImagesOutputImage
// @failure 400 // @failure 400
// @failure 401 // @failure 401
// @router /api/images [get] // @router /api/images [get]

23
handlers/api/postImage.go Normal file
View File

@@ -0,0 +1,23 @@
package api
import (
"net/http"
"gitea.konchin.com/go2025/backend/utils"
"github.com/uptrace/bunrouter"
)
// PostImage
//
// @param userinfo header string true "userinfo from /auth/gen-login-url"
// @accept image/png
// @accept image/jpeg
// @accept image/gif
// @success 200
// @failure 401
// @router /api/image [post]
func (self *Handlers) PostImage(
w http.ResponseWriter, req bunrouter.Request,
) error {
return utils.Success(w)
}

24
handlers/api/putImageAliases.go Normal file
View File

@@ -0,0 +1,24 @@
package api
import (
"net/http"
"gitea.konchin.com/go2025/backend/utils"
"github.com/uptrace/bunrouter"
)
type putImageAliasesInputAlias = string
// PutImageAliases
//
// @param id path int64 true "Image Id"
// @param payload body []putImageAliasesInputAlias true "Payload"
// @success 200
// @failure 401
// @failure 404
// @router /api/image/{id}/aliases [put]
func (self *Handlers) PutImageAliases(
w http.ResponseWriter, req bunrouter.Request,
) error {
return utils.Success(w)
}

28
handlers/auth/postGenLoginUrl.go Normal file
View File

@@ -0,0 +1,28 @@
package auth
import (
"net/http"
"gitea.konchin.com/go2025/backend/utils"
"github.com/uptrace/bunrouter"
)
type postGenLoginUrlInput struct {
UserId string `json:"userId"`
}
type postGenLoginUrlOutput struct {
LoginUrl string `json:"loginUrl"`
}
// PostGenLoginUrl
//
// @param payload body postGenLoginUrlInput true "Payload"
// @success 200 {object} postGenLoginUrlOutput "Payload"
// @failure 400
// @router /auth/gen-login-url [post]
func (self *Handlers) PostGenLoginUrl(
w http.ResponseWriter, req bunrouter.Request,
) error {
return utils.Success(w)
}