Cleanup openapi generation

.cspell.json

@@ -129,6 +129,7 @@
     "nosniff",
     "ntfy",
     "octocat",
+    "openapi",
     "opensource",
     "Pacman",
     "picus",
@@ -250,7 +251,7 @@
     "flake.lock",
     "pnpm-lock.yaml",
     "**/node_modules/**/*",
-    "cmd/server/docs/docs.go",
+    "cmd/server/openapi/docs.go",
     "renovate.json",
     // TODO: remove the following
     "docs/**/*.js",

.ecrc

@@ -1,14 +1,15 @@
 {
   "Exclude": [
     ".git",
-    "go.mod", "go.sum",
+    "go.mod",
+    "go.sum",
     "vendor",
     "fixtures",
     "LICENSE",
     "node_modules",
     "server/store/datastore/migration/test-files/sqlite.db",
     "server/store/datastore/feed.go",
-    "cmd/server/docs/docs.go",
+    "cmd/server/openapi/docs.go",
     "_test.go",
     "Makefile"
   ]

.gitignore

@@ -51,4 +51,4 @@ docs/venv
 
 ### Generated by CI ###
 docs/docs/40-cli.md
-docs/swagger.json
+docs/openapi.json

.woodpecker/test.yaml

@@ -63,14 +63,14 @@ steps:
       - make lint
     when: *when
 
-  check-swagger:
+  check-openapi:
     depends_on:
       - vendor
     image: *golang_image
     commands:
-      - 'make generate-swagger'
+      - 'make generate-openapi'
       - 'DIFF=$(git diff | head)'
-      - '[ -n "$DIFF" ] && { echo "swagger not up to date, exec `make generate-swagger` and commit"; exit 1; } || true'
+      - '[ -n "$DIFF" ] && { echo "openapi not up to date, exec `make generate-openapi` and commit"; exit 1; } || true'
     when: *when
 
   lint-license-header:

Makefile

@@ -109,15 +109,15 @@ clean: ## Clean build artifacts
 clean-all: clean ## Clean all artifacts
 	rm -rf ${DIST_DIR} web/dist docs/build docs/node_modules web/node_modules
 	# delete generated
-	rm -rf docs/docs/40-cli.md docs/swagger.json
+	rm -rf docs/docs/40-cli.md docs/openapi.json
 
 .PHONY: generate
-generate: install-tools generate-swagger ## Run all code generations
+generate: install-tools generate-openapi ## Run all code generations
 	CGO_ENABLED=0 go generate ./...
 
-generate-swagger: install-tools ## Run swagger code generation
-	swag init -g server/api/ -g cmd/server/swagger.go --outputTypes go -output cmd/server/docs
-	CGO_ENABLED=0 go generate cmd/server/swagger.go
+generate-openapi: install-tools ## Run openapi code generation and format it
+	go run github.com/swaggo/swag/cmd/swag fmt
+	CGO_ENABLED=0 go generate cmd/server/openapi.go
 
 generate-license-header: install-tools
 	addlicense -c "Woodpecker Authors" -ignore "vendor/**" **/*.go
@@ -134,9 +134,6 @@ install-tools: ## Install development tools
 	hash gofumpt > /dev/null 2>&1; if [ $$? -ne 0 ]; then \
 		go install mvdan.cc/gofumpt@latest; \
 	fi ; \
-	hash swag > /dev/null 2>&1; if [ $$? -ne 0 ]; then \
-		go install github.com/swaggo/swag/cmd/swag@latest; \
-	fi ; \
 	hash addlicense > /dev/null 2>&1; if [ $$? -ne 0 ]; then \
 		go install github.com/google/addlicense@latest; \
 	fi ; \
@@ -196,7 +193,7 @@ test: test-agent test-server test-server-datastore test-cli test-lib ## Run all
 build-ui: ## Build UI
 	(cd web/; pnpm install --frozen-lockfile; pnpm build)
 
-build-server: build-ui generate-swagger ## Build server
+build-server: build-ui generate-openapi ## Build server
 	CGO_ENABLED=${CGO_ENABLED} GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -tags '$(TAGS)' -ldflags '${LDFLAGS}' -o ${DIST_DIR}/woodpecker-server${BIN_SUFFIX} go.woodpecker-ci.org/woodpecker/v2/cmd/server
 
 build-agent: ## Build agent
@@ -343,6 +340,6 @@ spellcheck:
 .PHONY: docs
 docs: ## Generate docs (currently only for the cli)
 	CGO_ENABLED=0 go generate cmd/cli/app.go
-	CGO_ENABLED=0 go generate cmd/server/swagger.go
+	CGO_ENABLED=0 go generate cmd/server/openapi.go
 
 endif

cmd/server/main.go

@@ -12,6 +12,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//go:build !generate
+// +build !generate
+
 package main
 
 import (
@@ -22,7 +25,7 @@ import (
 	"github.com/rs/zerolog/log"
 	"github.com/urfave/cli/v3"
 
-	_ "go.woodpecker-ci.org/woodpecker/v2/cmd/server/docs"
+	_ "go.woodpecker-ci.org/woodpecker/v2/cmd/server/openapi"
 	"go.woodpecker-ci.org/woodpecker/v2/shared/utils"
 	"go.woodpecker-ci.org/woodpecker/v2/version"
 )
@@ -46,7 +49,7 @@ func main() {
 	}
 	app.Flags = flags
 
-	setupSwaggerStaticConfig()
+	setupOpenAPIStaticConfig()
 
 	if err := app.Run(ctx, os.Args); err != nil {
 		log.Error().Err(err).Msgf("error running server")

cmd/server/openapi.go

@@ -0,0 +1,38 @@
+// Copyright 2023 Woodpecker Authors
+//
+// Licensed 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 main
+
+import (
+	"go.woodpecker-ci.org/woodpecker/v2/cmd/server/openapi"
+	"go.woodpecker-ci.org/woodpecker/v2/version"
+)
+
+// Generate docs/openapi.json via:
+//go:generate go run github.com/swaggo/swag/cmd/swag init -g cmd/server/openapi.go --outputTypes go -output openapi -d ../../
+//go:generate go run openapi_json_gen.go openapi.go
+//go:generate go run github.com/getkin/kin-openapi/cmd/validate@latest ../../docs/openapi.json
+
+// setupOpenAPIStaticConfig initializes static content (version) for the OpenAPI config.
+//
+//	@title			Woodpecker CI API
+//	@description	Woodpecker is a simple, yet powerful CI/CD engine with great extensibility.
+//	@description	To get a personal access token (PAT) for authentication, please log in your Woodpecker server,
+//	@description	and go to you personal profile page, by clicking the user icon at the top right.
+//	@BasePath		/api
+//	@contact.name	Woodpecker CI
+//	@contact.url	https://woodpecker-ci.org/
+func setupOpenAPIStaticConfig() {
+	openapi.SwaggerInfo.Version = version.String()
+}

cmd/server/docs/docs.go → cmd/server/openapi/docs.go

@@ -1,5 +1,5 @@
-// Package docs Code generated by swaggo/swag. DO NOT EDIT
-package docs
+// Package openapi Code generated by swaggo/swag. DO NOT EDIT
+package openapi
 
 import "github.com/swaggo/swag"
 
@@ -10,7 +10,7 @@ const docTemplate = `{
         "description": "{{escape .Description}}",
         "title": "{{.Title}}",
         "contact": {
-            "name": "Woodpecker CI Community",
+            "name": "Woodpecker CI",
             "url": "https://woodpecker-ci.org/"
         },
         "version": "{{.Version}}"
@@ -122,7 +122,7 @@ const docTemplate = `{
                     {
                         "type": "integer",
                         "description": "the agent's id",
-                        "name": "agent",
+                        "name": "agent_id",
                         "in": "path",
                         "required": true
                     }
@@ -156,7 +156,7 @@ const docTemplate = `{
                     {
                         "type": "integer",
                         "description": "the agent's id",
-                        "name": "agent",
+                        "name": "agent_id",
                         "in": "path",
                         "required": true
                     }
@@ -187,7 +187,7 @@ const docTemplate = `{
                     {
                         "type": "integer",
                         "description": "the agent's id",
-                        "name": "agent",
+                        "name": "agent_id",
                         "in": "path",
                         "required": true
                     },
@@ -232,7 +232,7 @@ const docTemplate = `{
                     {
                         "type": "integer",
                         "description": "the agent's id",
-                        "name": "agent",
+                        "name": "agent_id",
                         "in": "path",
                         "required": true
                     }
@@ -4554,22 +4554,15 @@ const docTemplate = `{
                     "200": {
                         "description": "OK",
                         "schema": {
-                            "allOf": [
-                                {
+                            "type": "object",
+                            "properties": {
+                                "source": {
                                     "type": "string"
                                 },
-                                {
-                                    "type": "object",
-                                    "properties": {
-                                        "source": {
-                                            "type": "string"
-                                        },
-                                        "version": {
-                                            "type": "string"
-                                        }
-                                    }
+                                "version": {
+                                    "type": "string"
                                 }
-                            ]
+                            }
                         }
                     }
                 }
@@ -5791,10 +5784,10 @@ const docTemplate = `{
 var SwaggerInfo = &swag.Spec{
 	Version:          "",
 	Host:             "",
-	BasePath:         "",
+	BasePath:         "/api",
 	Schemes:          []string{},
-	Title:            "",
-	Description:      "",
+	Title:            "Woodpecker CI API",
+	Description:      "Woodpecker is a simple, yet powerful CI/CD engine with great extensibility.\nTo get a personal access token (PAT) for authentication, please log in your Woodpecker server,\nand go to you personal profile page, by clicking the user icon at the top right.",
 	InfoInstanceName: "swagger",
 	SwaggerTemplate:  docTemplate,
 	LeftDelim:        "{{",

cmd/server/woodpecker_docs_gen.go → cmd/server/openapi_json_gen.go

@@ -12,9 +12,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// ************************************************************************************************
-// This is a generator tool, to update the Markdown documentation for the woodpecker-ci.org website
-// ************************************************************************************************
+// *********************************************************
+// This is a generator tool, to update the openapi.json file
+// *********************************************************
 
 //go:build generate
 // +build generate
@@ -30,23 +30,24 @@ import (
 
 	"github.com/getkin/kin-openapi/openapi2"
 	"github.com/getkin/kin-openapi/openapi2conv"
-	"go.woodpecker-ci.org/woodpecker/v2/cmd/server/docs"
+
+	"go.woodpecker-ci.org/woodpecker/v2/cmd/server/openapi"
 )
 
 func main() {
-	// set swagger infos
-	setupSwaggerStaticConfig()
+	// set openapi infos
+	setupOpenAPIStaticConfig()
 
 	basePath := path.Join("..", "..")
-	filePath := path.Join(basePath, "docs", "swagger.json")
+	filePath := path.Join(basePath, "docs", "openapi.json")
 
-	// generate swagger file
+	// generate openapi file
 	f, err := os.Create(filePath)
 	if err != nil {
 		panic(err)
 	}
 	defer f.Close()
-	doc := docs.SwaggerInfo.ReadDoc()
+	doc := openapi.SwaggerInfo.ReadDoc()
 	doc, err = removeHost(doc)
 	if err != nil {
 		panic(err)
@@ -56,6 +57,8 @@ func main() {
 		panic(err)
 	}
 
+	fmt.Println("generated openapi.json")
+
 	// convert to OpenApi3
 	if err := toOpenApi3(filePath, filePath); err != nil {
 		fmt.Printf("converting '%s' from openapi v2 to v3 failed\n", filePath)

cmd/server/openapi_test.go

@@ -0,0 +1,14 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"go.woodpecker-ci.org/woodpecker/v2/cmd/server/openapi"
+)
+
+func TestSetupOpenApiStaticConfig(t *testing.T) {
+	setupOpenAPIStaticConfig()
+	assert.Equal(t, "/api", openapi.SwaggerInfo.BasePath)
+}