[Docs] use redocusaurus to display swagger file (#1818)

https://redocusaurus.vercel.app/

followup of  #1782

---------

Co-authored-by: Anbraten <[email protected]>

.gitignore

@@ -48,4 +48,4 @@ docs/venv
 
 ### Generated by CI ###
 docs/docs/40-cli.md
-docs/docs/20-usage/90-rest-api.md
+docs/swagger.json

cmd/server/swagger.go

@@ -19,7 +19,7 @@ import (
 	"github.com/woodpecker-ci/woodpecker/version"
 )
 
-// generate docs/docs/20-usage/90-rest-api.md via:
+// generate docs/swagger.json via:
 //go:generate go run woodpecker_docs_gen.go swagger.go
 
 // setupSwaggerStaticConfig initializes static content only (contacts, title and description)

cmd/server/woodpecker_docs_gen.go

@@ -22,67 +22,18 @@
 package main
 
 import (
-	"bufio"
-	"fmt"
 	"os"
 	"path"
-	"strings"
-	"time"
-
-	"github.com/go-swagger/go-swagger/generator"
 
 	"github.com/woodpecker-ci/woodpecker/cmd/server/docs"
 )
 
-const restApiMarkdownInto = `
-# REST API
-
-Woodpecker offers a comprehensive REST API, so you can integrate easily with from and with other tools.
-
-## API specification
-
-Starting with Woodpecker v1.0.0 a Swagger v2 API specification is served by the Woodpecker Server.
-The typical URL looks like "http://woodpecker-host/swagger/doc.json", where you can fetch the API specification.
-
-## Swagger API UI
-
-Starting with Woodpecker v1.0.0 a Swagger web user interface (UI) is served by the Woodpecker Server.
-Typically, you can open "http://woodpecker-host/swagger/index.html" in your browser, to explore the API documentation.
-
-# API endpoint summary
-
-This is a summary of available API endpoints.
-Please, keep in mind this documentation reflects latest development changes
-and might differ from your used server version.
-Its recommended to consult the Swagger API UI of your Woodpecker server,
-where you also have the chance to do manual exploration and live testing.
-
-`
-
 func main() {
+	// set swagger infos
 	setupSwaggerStaticConfig()
 
-	specFile := createTempFileWithSwaggerSpec()
-	defer os.Remove(specFile)
-	markdown := generateTempMarkdown(specFile)
-
-	f, err := os.Create(path.Join("..", "..", "docs", "docs", "20-usage", "90-rest-api.md"))
-	if err != nil {
-		panic(err)
-	}
-	defer f.Close()
-	_, err = f.WriteString(restApiMarkdownInto)
-	if err != nil {
-		panic(err)
-	}
-	_, err = f.WriteString(readGeneratedMarkdownAndSkipIntro(markdown))
-	if err != nil {
-		panic(err)
-	}
-}
-
-func createTempFileWithSwaggerSpec() string {
-	f, err := os.CreateTemp(os.TempDir(), "swagger.json")
+	// generate swagger file
+	f, err := os.Create(path.Join("..", "..", "docs", "swagger.json"))
 	if err != nil {
 		panic(err)
 	}
@@ -91,44 +42,4 @@ func createTempFileWithSwaggerSpec() string {
 	if err != nil {
 		panic(err)
 	}
-	return f.Name()
-}
-
-func generateTempMarkdown(specFile string) string {
-	// HINT: we MUST use underscores, since the library tends to rename things
-	tempFile := fmt.Sprintf("woodpecker_api_%d.md", time.Now().UnixMilli())
-	markdownFile := path.Join(os.TempDir(), tempFile)
-
-	opts := generator.GenOpts{
-		GenOptsCommon: generator.GenOptsCommon{
-			Spec: specFile,
-		},
-	}
-	// TODO: contrib upstream a GenerateMarkdown that use io.Reader and io.Writer
-	err := generator.GenerateMarkdown(markdownFile, []string{}, []string{}, &opts)
-	if err != nil {
-		panic(err)
-	}
-
-	data, err := os.ReadFile(markdownFile)
-	if err != nil {
-		panic(err)
-	}
-	defer os.Remove(markdownFile)
-
-	return string(data)
-}
-
-func readGeneratedMarkdownAndSkipIntro(markdown string) string {
-	scanner := bufio.NewScanner(strings.NewReader(markdown))
-	sb := strings.Builder{}
-	foundActualContentStart := false
-	for scanner.Scan() {
-		text := scanner.Text()
-		foundActualContentStart = foundActualContentStart || (strings.HasPrefix(text, "##") && strings.Contains(strings.ToLower(text), "all endpoints"))
-		if foundActualContentStart {
-			sb.WriteString(text + "\n")
-		}
-	}
-	return sb.String()
 }

docs/docusaurus.config.js

@@ -53,6 +53,11 @@ module.exports = {
             position: 'left',
             label: 'Awesome',
           },
+          {
+            to: '/api',
+            position: 'left',
+            label: 'API',
+          },
           {
             type: 'docsVersionDropdown',
             position: 'right',
@@ -223,6 +228,23 @@ module.exports = {
         },
       }),
     ],
+    [
+      'redocusaurus',
+      {
+        // Plugin Options for loading OpenAPI files
+        specs: [
+          {
+            spec: 'swagger.json',
+            route: '/api/',
+          },
+        ],
+        // Theme Options for modifying how redoc renders them
+        theme: {
+          // Change with your site colors
+          primaryColor: '#1890ff',
+        },
+      },
+    ],
   ],
   webpack: {
     jsLoader: (isServer) => ({

docs/package.json

@@ -3,8 +3,7 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "docusaurus": "docusaurus",
-    "start": "docusaurus start",
+    "start": "cd ../ && make docs && cd docs && docusaurus start",
     "build": "pnpm build:woodpecker-plugins && docusaurus build",
     "build:woodpecker-plugins": "cd plugins/woodpecker-plugins && pnpm i && pnpm build",
     "swizzle": "docusaurus swizzle",
@@ -26,6 +25,7 @@
     "prism-react-renderer": "^1.3.5",
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
+    "redocusaurus": "^1.6.2",
     "url-loader": "^4.1.1"
   },
   "browserslist": {