diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 17a1b53..5e1f2ab 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -20,7 +20,7 @@ jobs: python-version: 3.x - name: Install dependencies - run: pip install mike mkdocs-material[imaging] mkdocs-minify-plugin + run: pip install mike mkdocs-material[imaging] mkdocs-minify-plugin mkdocs-swagger-ui-tag - name: Publish documentation run: mike deploy --push --update-aliases ${{ github.ref_name }} latest diff --git a/cmd/api_build_tool/main.go b/cmd/api_build_tool/main.go index 9bad0b1..a48f89f 100644 --- a/cmd/api_build_tool/main.go +++ b/cmd/api_build_tool/main.go @@ -12,6 +12,10 @@ import ( "github.com/swaggo/swag/gen" ) +var apiRootPath = "/internal/app/api" +var apiDocPath = "core/assets/doc" +var apiMkDocPath = "/docs/documentation/rest-api" + // this replaces the call to: swag init --propertyStrategy pascalcase --parseDependency --parseInternal --generalInfo base.go func main() { wd, err := os.Getwd() // should be the project root @@ -19,7 +23,7 @@ func main() { panic(err) } - apiBasePath := filepath.Join(wd, "/internal/app/api") + apiBasePath := filepath.Join(wd, apiRootPath) apis := []string{"v0", "v1"} hasError := false @@ -37,6 +41,15 @@ func main() { logrus.Errorf("failed to generate API docs for %s: %v", apiVersion, err) } + // copy the latest version of the API docs for mkdocs + if apiVersion == apis[len(apis)-1] { + if err = copyDocForMkdocs(wd, apiBasePath, apiVersion); err != nil { + logrus.Errorf("failed to copy API docs for mkdocs: %v", err) + } else { + log.Println("Copied API docs " + apiVersion + " for mkdocs") + } + } + log.Println("Generated swagger docs for API", apiVersion) } @@ -51,7 +64,7 @@ func generateApi(basePath, apiPath, version string) error { Excludes: "", MainAPIFile: "base.go", PropNamingStrategy: swag.PascalCase, - OutputDir: filepath.Join(basePath, "core/assets/doc"), + OutputDir: filepath.Join(basePath, apiDocPath), OutputTypes: []string{"json", "yaml"}, ParseVendor: false, ParseDependency: 3, @@ -68,3 +81,21 @@ func generateApi(basePath, apiPath, version string) error { return nil } + +func copyDocForMkdocs(workingDir, basePath, version string) error { + srcPath := filepath.Join(basePath, apiDocPath, fmt.Sprintf("%s_swagger.yaml", version)) + dstPath := filepath.Join(workingDir, apiMkDocPath, "swagger.yaml") + + // copy the file + input, err := os.ReadFile(srcPath) + if err != nil { + return fmt.Errorf("error while reading swagger doc: %w", err) + } + + err = os.WriteFile(dstPath, input, 0644) + if err != nil { + return fmt.Errorf("error while writing swagger doc: %w", err) + } + + return nil +} diff --git a/docs/documentation/overview.md b/docs/documentation/overview.md index 770d8fb..87429e8 100644 --- a/docs/documentation/overview.md +++ b/docs/documentation/overview.md @@ -21,7 +21,7 @@ The configuration portal supports using a database (SQLite, MySQL, MsSQL or Post * Support for multiple WireGuard interfaces * Peer Expiry Feature * Handle route and DNS settings like wg-quick does -* ~~REST API for management and client deployment~~ (coming soon) +* REST API for management and client deployment ## Quick-Start diff --git a/docs/documentation/rest-api/api-doc.md b/docs/documentation/rest-api/api-doc.md new file mode 100644 index 0000000..92a5bd1 --- /dev/null +++ b/docs/documentation/rest-api/api-doc.md @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 553a420..83160d6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,7 +4,7 @@ site_description: Manage WireGuard Peers and Interface using a beautiful and sim site_url: https://wgportal.org/ repo_name: h44z/wg-portal repo_url: https://github.com/h44z/wg-portal -copyright: Copyright © 2023-2024 WireGuard Portal Project +copyright: Copyright © 2023-2025 WireGuard Portal Project extra_css: - stylesheets/extra.css @@ -27,6 +27,7 @@ plugins: - social - minify: minify_html: true + - swagger-ui-tag extra: version: @@ -60,3 +61,4 @@ nav: - Building: documentation/getting-started/building.md - Docker Container: documentation/getting-started/docker.md - Upgrade from V1: documentation/getting-started/upgrade.md + - REST API: documentation/rest-api/api-doc.md