Skip to content

A Q&A platform software for teams at any scales. Whether it's a community forum, help center, or knowledge management platform, you can always count on Apache Answer.

build swagger documentation on go generate

Jan Ernsting15531f422314
diff --git a/cmd/answer/main.go b/cmd/answer/main.go
index ae114709..a14031ec 100644
--- a/cmd/answer/main.go
+++ b/cmd/answer/main.go
@@ -17,12 +17,19 @@
* under the License.
*/
+//go:generate go run github.com/swaggo/swag/cmd/swag init -g ./cmd/answer/main.go -d ../../ -o ../../docs
+
package main
import (
answercmd "github.com/apache/incubator-answer/cmd"
)
+// main godoc
+// @title "answer"
+// @description = "answer api"
+// @version = "v0.0.1"
+// @BasePath = "/"
// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name Authorization
diff --git a/docs/docs.go b/docs/docs.go
index cf1264d1..fee91459 100644
--- a/docs/docs.go
+++ b/docs/docs.go
@@ -1,22 +1,3 @@
-/*
- * Licensed to the Apache Software Foundation (ASF) under one
- * or more contributor license agreements. See the NOTICE file
- * distributed with this work for additional information
- * regarding copyright ownership. The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance
- * with the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing,
- * software distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- * KIND, either express or implied. See the License for the
- * specific language governing permissions and limitations
- * under the License.
- */
-
// Package docs Code generated by swaggo/swag. DO NOT EDIT
package docs
@@ -4410,7 +4391,7 @@ const docTemplate = `{
"data": {
"type": "array",
"items": {
- "$ref": "#/definitions/schema.GetTagResp"
+ "$ref": "#/definitions/schema.GetTagBasicResp"
}
}
}
@@ -5380,7 +5361,7 @@ const docTemplate = `{
},
"/answer/api/v1/tags": {
"get": {
- "description": "get tags list",
+ "description": "get tags list by slug name",
"produces": [
"application/json"
],
@@ -5404,7 +5385,22 @@ const docTemplate = `{
"200": {
"description": "OK",
"schema": {
- "$ref": "#/definitions/handler.RespBody"
+ "allOf": [
+ {
+ "$ref": "#/definitions/handler.RespBody"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/schema.GetTagBasicResp"
+ }
+ }
+ }
+ }
+ ]
}
}
}
@@ -8242,6 +8238,23 @@ const docTemplate = `{
}
}
},
+ "schema.GetTagBasicResp": {
+ "type": "object",
+ "properties": {
+ "display_name": {
+ "type": "string"
+ },
+ "recommend": {
+ "type": "boolean"
+ },
+ "reserved": {
+ "type": "boolean"
+ },
+ "slug_name": {
+ "type": "string"
+ }
+ }
+ },
"schema.GetTagPageResp": {
"type": "object",
"properties": {
@@ -9819,7 +9832,7 @@ const docTemplate = `{
"recommend_tags": {
"type": "array",
"items": {
- "type": "string"
+ "$ref": "#/definitions/schema.SiteWriteTag"
}
},
"required_tag": {
@@ -9828,7 +9841,7 @@ const docTemplate = `{
"reserved_tags": {
"type": "array",
"items": {
- "type": "string"
+ "$ref": "#/definitions/schema.SiteWriteTag"
}
},
"restrict_answer": {
@@ -9842,7 +9855,7 @@ const docTemplate = `{
"recommend_tags": {
"type": "array",
"items": {
- "type": "string"
+ "$ref": "#/definitions/schema.SiteWriteTag"
}
},
"required_tag": {
@@ -9851,7 +9864,7 @@ const docTemplate = `{
"reserved_tags": {
"type": "array",
"items": {
- "type": "string"
+ "$ref": "#/definitions/schema.SiteWriteTag"
}
},
"restrict_answer": {
@@ -9859,6 +9872,20 @@ const docTemplate = `{
}
}
},
+ "schema.SiteWriteTag": {
+ "type": "object",
+ "required": [
+ "slug_name"
+ ],
+ "properties": {
+ "display_name": {
+ "type": "string"
+ },
+ "slug_name": {
+ "type": "string"
+ }
+ }
+ },
"schema.TagItem": {
"type": "object",
"properties": {
@@ -10783,12 +10810,12 @@ const docTemplate = `{
// SwaggerInfo holds exported Swagger Info so clients can modify it
var SwaggerInfo = &swag.Spec{
- Version: "",
+ Version: "= \"v0.0.1\"",
Host: "",
- BasePath: "",
+ BasePath: "= \"/\"",
Schemes: []string{},
- Title: "",
- Description: "",
+ Title: "\"answer\"",
+ Description: "= \"answer api\"",
InfoInstanceName: "swagger",
SwaggerTemplate: docTemplate,
LeftDelim: "{{",
diff --git a/docs/swagger.json b/docs/swagger.json
index 1e93d2b0..7c103856 100644
--- a/docs/swagger.json
+++ b/docs/swagger.json
@@ -1,8 +1,12 @@
{
"swagger": "2.0",
"info": {
- "contact": {}
+ "description": "= \"answer api\"",
+ "title": "\"answer\"",
+ "contact": {},
+ "version": "= \"v0.0.1\""
},
+ "basePath": "= \"/\"",
"paths": {
"/": {
"get": {
@@ -4380,7 +4384,7 @@
"data": {
"type": "array",
"items": {
- "$ref": "#/definitions/schema.GetTagResp"
+ "$ref": "#/definitions/schema.GetTagBasicResp"
}
}
}
@@ -5350,7 +5354,7 @@
},
"/answer/api/v1/tags": {
"get": {
- "description": "get tags list",
+ "description": "get tags list by slug name",
"produces": [
"application/json"
],
@@ -5374,7 +5378,22 @@
"200": {
"description": "OK",
"schema": {
- "$ref": "#/definitions/handler.RespBody"
+ "allOf": [
+ {
+ "$ref": "#/definitions/handler.RespBody"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/schema.GetTagBasicResp"
+ }
+ }
+ }
+ }
+ ]
}
}
}
@@ -8212,6 +8231,23 @@
}
}
},
+ "schema.GetTagBasicResp": {
+ "type": "object",
+ "properties": {
+ "display_name": {
+ "type": "string"
+ },
+ "recommend": {
+ "type": "boolean"
+ },
+ "reserved": {
+ "type": "boolean"
+ },
+ "slug_name": {
+ "type": "string"
+ }
+ }
+ },
"schema.GetTagPageResp": {
"type": "object",
"properties": {
@@ -8809,7 +8845,7 @@
"enum": [
"newest",
"active",
- "frequent",
+ "hot",
"score",
"unanswered"
]
@@ -9789,7 +9825,7 @@
"recommend_tags": {
"type": "array",
"items": {
- "type": "string"
+ "$ref": "#/definitions/schema.SiteWriteTag"
}
},
"required_tag": {
@@ -9798,7 +9834,7 @@
"reserved_tags": {
"type": "array",
"items": {
- "type": "string"
+ "$ref": "#/definitions/schema.SiteWriteTag"
}
},
"restrict_answer": {
@@ -9812,7 +9848,7 @@
"recommend_tags": {
"type": "array",
"items": {
- "type": "string"
+ "$ref": "#/definitions/schema.SiteWriteTag"
}
},
"required_tag": {
@@ -9821,7 +9857,7 @@
"reserved_tags": {
"type": "array",
"items": {
- "type": "string"
+ "$ref": "#/definitions/schema.SiteWriteTag"
}
},
"restrict_answer": {
@@ -9829,6 +9865,20 @@
}
}
},
+ "schema.SiteWriteTag": {
+ "type": "object",
+ "required": [
+ "slug_name"
+ ],
+ "properties": {
+ "display_name": {
+ "type": "string"
+ },
+ "slug_name": {
+ "type": "string"
+ }
+ }
+ },
"schema.TagItem": {
"type": "object",
"properties": {
diff --git a/docs/swagger.yaml b/docs/swagger.yaml
index 93f8116a..231b271e 100644
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -1,20 +1,4 @@
-# Licensed to the Apache Software Foundation (ASF) under one
-# or more contributor license agreements. See the NOTICE file
-# distributed with this work for additional information
-# regarding copyright ownership. The ASF licenses this file
-# to you under the Apache License, Version 2.0 (the
-# "License"); you may not use this file except in compliance
-# with the License. You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing,
-# software distributed under the License is distributed on an
-# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-# KIND, either express or implied. See the License for the
-# specific language governing permissions and limitations
-# under the License.
-
+basePath: = "/"
definitions:
constant.NotificationChannelKey:
enum:
@@ -983,6 +967,17 @@ definitions:
terms_of_service_parsed_text:
type: string
type: object
+ schema.GetTagBasicResp:
+ properties:
+ display_name:
+ type: string
+ recommend:
+ type: boolean
+ reserved:
+ type: boolean
+ slug_name:
+ type: string
+ type: object
schema.GetTagPageResp:
properties:
created_at:
@@ -1401,7 +1396,7 @@ definitions:
enum:
- newest
- active
- - frequent
+ - hot
- score
- unanswered
type: string
@@ -2071,13 +2066,13 @@ definitions:
properties:
recommend_tags:
items:
- type: string
+ $ref: '#/definitions/schema.SiteWriteTag'
type: array
required_tag:
type: boolean
reserved_tags:
items:
- type: string
+ $ref: '#/definitions/schema.SiteWriteTag'
type: array
restrict_answer:
type: boolean
@@ -2086,17 +2081,26 @@ definitions:
properties:
recommend_tags:
items:
- type: string
+ $ref: '#/definitions/schema.SiteWriteTag'
type: array
required_tag:
type: boolean
reserved_tags:
items:
- type: string
+ $ref: '#/definitions/schema.SiteWriteTag'
type: array
restrict_answer:
type: boolean
type: object
+ schema.SiteWriteTag:
+ properties:
+ display_name:
+ type: string
+ slug_name:
+ type: string
+ required:
+ - slug_name
+ type: object
schema.TagItem:
properties:
display_name:
@@ -2736,6 +2740,9 @@ definitions:
type: object
info:
contact: {}
+ description: = "answer api"
+ title: '"answer"'
+ version: = "v0.0.1"
paths:
/:
get:
@@ -5382,7 +5389,7 @@ paths:
- properties:
data:
items:
- $ref: '#/definitions/schema.GetTagResp'
+ $ref: '#/definitions/schema.GetTagBasicResp'
type: array
type: object
security:
@@ -5965,7 +5972,7 @@ paths:
- Tag
/answer/api/v1/tags:
get:
- description: get tags list
+ description: get tags list by slug name
parameters:
- collectionFormat: csv
description: string collection
@@ -5980,7 +5987,14 @@ paths:
"200":
description: OK
schema:
- $ref: '#/definitions/handler.RespBody'
+ allOf:
+ - $ref: '#/definitions/handler.RespBody'
+ - properties:
+ data:
+ items:
+ $ref: '#/definitions/schema.GetTagBasicResp'
+ type: array
+ type: object
summary: get tags list
tags:
- Tag
diff --git a/go.mod b/go.mod
index e1b78ad2..036a2b42 100644
--- a/go.mod
+++ b/go.mod
@@ -54,7 +54,7 @@ require (
github.com/stretchr/testify v1.8.4
github.com/swaggo/files v1.0.0
github.com/swaggo/gin-swagger v1.5.3
- github.com/swaggo/swag v1.16.1
+ github.com/swaggo/swag v1.16.3
github.com/tidwall/gjson v1.14.4
github.com/yuin/goldmark v1.4.13
golang.org/x/crypto v0.21.0
@@ -79,6 +79,7 @@ require (
github.com/cenkalti/backoff/v4 v4.2.1 // indirect
github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311 // indirect
github.com/containerd/continuity v0.4.2 // indirect
+ github.com/cpuguy83/go-md2man/v2 v2.0.2 // indirect
github.com/davecgh/go-spew v1.1.1 // indirect
github.com/docker/cli v24.0.6+incompatible // indirect
github.com/docker/docker v24.0.6+incompatible // indirect
@@ -128,6 +129,7 @@ require (
github.com/pkg/errors v0.9.1 // indirect
github.com/pmezard/go-difflib v1.0.0 // indirect
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+ github.com/russross/blackfriday/v2 v2.1.0 // indirect
github.com/sirupsen/logrus v1.9.3 // indirect
github.com/spf13/afero v1.9.2 // indirect
github.com/spf13/cast v1.5.0 // indirect
@@ -140,6 +142,7 @@ require (
github.com/tidwall/pretty v1.2.0 // indirect
github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
github.com/ugorji/go/codec v1.2.11 // indirect
+ github.com/urfave/cli/v2 v2.3.0 // indirect
github.com/xeipuuv/gojsonpointer v0.0.0-20190905194746-02993c407bfb // indirect
github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
github.com/xeipuuv/gojsonschema v1.2.0 // indirect
diff --git a/go.sum b/go.sum
index 501d1e94..fb49b88b 100644
--- a/go.sum
+++ b/go.sum
@@ -128,6 +128,7 @@ github.com/coreos/go-systemd v0.0.0-20190321100706-95778dfbb74e/go.mod h1:F5haX7
github.com/coreos/go-systemd v0.0.0-20190719114852-fd7a80b32e1f/go.mod h1:F5haX7vjVVG0kc13fIWeqUViNPyEJxv/OmvnBo0Yme4=
github.com/coreos/pkg v0.0.0-20160727233714-3ac0863d7acf/go.mod h1:E3G3o1h8I7cfcXa63jLwjI0eiQQMgzzUDFVpN/nH/eA=
github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
+github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w=
github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
github.com/creack/pty v1.1.7/go.mod h1:lj5s0c3V2DBrqTV7llrYr5NG6My20zk30Fl46Y7DoTY=
github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
@@ -615,6 +616,7 @@ github.com/rs/xid v1.2.1/go.mod h1:+uKXf+4Djp6Md1KODXJxgGQPKngRmWyn10oCKFzNHOQ=
github.com/rs/zerolog v1.13.0/go.mod h1:YbFCdg8HfsridGWAh22vktObvhZbQsZXe4/zB0OKkWU=
github.com/rs/zerolog v1.15.0/go.mod h1:xYTKnLHcpfU2225ny5qZjxnj9NvkumZYjJHlAThCjNc=
github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
github.com/ryanuber/columnize v0.0.0-20160712163229-9b3edd62028f/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts=
github.com/samuel/go-zookeeper v0.0.0-20190923202752-2cc03de413da/go.mod h1:gi+0XIa01GRL2eRQVjQkKGqKF3SF9vZR/HnPullcV2E=
@@ -692,6 +694,8 @@ github.com/swaggo/gin-swagger v1.5.3/go.mod h1:3XJKSfHjDMB5dBo/0rrTXidPmgLeqsX89
github.com/swaggo/swag v1.8.1/go.mod h1:ugemnJsPZm/kRwFUnzBlbHRd0JY9zE1M4F+uy2pAaPQ=
github.com/swaggo/swag v1.16.1 h1:fTNRhKstPKxcnoKsytm4sahr8FaYzUcT7i1/3nd/fBg=
github.com/swaggo/swag v1.16.1/go.mod h1:9/LMvHycG3NFHfR6LwvikHv5iFvmPADQ359cKikGxto=
+github.com/swaggo/swag v1.16.3 h1:PnCYjPCah8FK4I26l2F/KQ4yz3sILcVUN3cTlBFA9Pg=
+github.com/swaggo/swag v1.16.3/go.mod h1:DImHIuOFXKpMFAQjcC7FG4m3Dg4+QuUgUzJmKjI/gRk=
github.com/syndtr/goleveldb v1.0.0 h1:fBdIW9lB4Iz0n9khmH8w27SJ3QEJ7+IgjPEwGSZiFdE=
github.com/syndtr/goleveldb v1.0.0/go.mod h1:ZVVdQEZoIme9iO1Ch2Jdy24qqXrMMOU6lpPAyBWyWuQ=
github.com/tidwall/gjson v1.14.4 h1:uo0p8EbA09J7RQaflQ1aBRffTR7xedD2bcIVSYxLnkM=
@@ -710,7 +714,9 @@ github.com/ugorji/go/codec v1.2.7/go.mod h1:WGN1fab3R1fzQlVQTkfxVtIBhWDRqOviHU95
github.com/ugorji/go/codec v1.2.11 h1:BMaWp1Bb6fHwEtbplGBGJ498wD+LKlNSl25MjdZY4dU=
github.com/ugorji/go/codec v1.2.11/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg=
github.com/urfave/cli v1.20.0/go.mod h1:70zkFmudgCuE/ngEzBv17Jvp/497gISqfk5gWijbERA=
+github.com/urfave/cli v1.22.1 h1:+mkCCcOFKPnCmVYVcURKps1Xe+3zP90gSYGNfRkjoIY=
github.com/urfave/cli v1.22.1/go.mod h1:Gos4lmkARVdJ6EkW0WaNv/tZAAMe9V7XWyB60NtXRu0=
+github.com/urfave/cli/v2 v2.3.0 h1:qph92Y649prgesehzOrQjdWyxFOp/QVM+6imKHad91M=
github.com/urfave/cli/v2 v2.3.0/go.mod h1:LJmUH05zAU44vOAcrfzZQKsZbVcdbOG8rtL3/XcUArI=
github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f/go.mod h1:N2zxlSyiKSe5eX1tZViRH5QA0qijqEDrYZiPEAiq3wU=
github.com/xeipuuv/gojsonpointer v0.0.0-20190905194746-02993c407bfb h1:zGWFAtiMcyryUHoUjUJX0/lt1H2+i2Ka2n+D3DImSNo=
diff --git a/internal/router/swagger_router.go b/internal/router/swagger_router.go
index 795e8802..55f2d644 100644
--- a/internal/router/swagger_router.go
+++ b/internal/router/swagger_router.go
@@ -51,9 +51,5 @@ func (a *SwaggerRouter) Register(r *gin.RouterGroup) {
// InitSwaggerDocs init swagger docs
func (a *SwaggerRouter) InitSwaggerDocs() {
- docs.SwaggerInfo.Title = "answer"
- docs.SwaggerInfo.Description = "answer api"
- docs.SwaggerInfo.Version = "v0.0.1"
docs.SwaggerInfo.Host = fmt.Sprintf("%s%s", a.config.Host, a.config.Address)
- docs.SwaggerInfo.BasePath = "/"
}