From b0c38a6257a6dfcb01b44fd793f0f3f646755691 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Weber?= Date: Tue, 28 May 2024 22:17:36 +0200 Subject: [PATCH] openapi: adjust to Hugo's build-in link render hook #860 - resolve render hook destination with leading ./ - configurable message for unresolved local adresses --- exampleSite/config/_default/params.toml | 10 ++++++++ .../content/basics/migration/_index.en.md | 2 ++ .../content/shortcodes/openapi/_index.en.md | 2 +- layouts/partials/shortcodes/openapi.html | 25 +++++++++++++------ 4 files changed, 31 insertions(+), 8 deletions(-) diff --git a/exampleSite/config/_default/params.toml b/exampleSite/config/_default/params.toml index f80705ad3f..b8634497b0 100644 --- a/exampleSite/config/_default/params.toml +++ b/exampleSite/config/_default/params.toml @@ -448,3 +448,13 @@ disableOpenapi = true # version will be used. # This can be overridden in the page's frontmatter. customOpenapiURL = "" # "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js" + +# What to do when a local OpenAPI spec link is not resolved. +# Default: "" +# You can control what should happen if a local OpenAPI spec link can not be resolved +# to a resource. If not set, the unresolved link is written as given into the resulting +# output. If set to `warning` the same happens and an additional warning is +# printed. If set to `error` an error message is printed and the build is +# aborted. +# Please note that this can not resolve files inside of your `static` directory. +openapi.errorlevel = "error" diff --git a/exampleSite/content/basics/migration/_index.en.md b/exampleSite/content/basics/migration/_index.en.md index ba9003064f..ac4f53c805 100644 --- a/exampleSite/content/basics/migration/_index.en.md +++ b/exampleSite/content/basics/migration/_index.en.md @@ -22,6 +22,8 @@ This document shows you what's new in the latest release and flags it with one o - {{% badge style="note" title=" " %}}Change{{% /badge %}} The [`include` shortcode](shortcodes/include) is now able to resolve links to pages as well as resources or files in the file system (the old behavior). +- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The [`openapi` shortcode](shortcodes/openapi) is now able to resolve links to resources as well as to files in the file system (the old behavior). You can configure to generate warnings or errors during build by setting `openapi.errorlevel` to either `warning` or `error` in your `hugo.toml` if a path can not be resolved. + --- ## 6.0.0 (2024-04-27) {#600} diff --git a/exampleSite/content/shortcodes/openapi/_index.en.md b/exampleSite/content/shortcodes/openapi/_index.en.md index f6b57d9d26..1e3685aba6 100644 --- a/exampleSite/content/shortcodes/openapi/_index.en.md +++ b/exampleSite/content/shortcodes/openapi/_index.en.md @@ -33,7 +33,7 @@ While the examples are using shortcodes with named parameter you are free to als | Name | Default | Notes | |----------------------|------------------|-------------| -| **src** | _<empty>_ | The URL to the OpenAPI specification file. This can be relative to the URL of your page if it is a leaf or branch bundle. | +| **src** | _<empty>_ | The path to the to the OpenAPI specification resource or URL to be used. Resource paths adhere to [Hugo's logical path](https://gohugo.io/methods/page/path/). | {{% notice note %}} If you want to print out (or generate a PDF) from your OpenAPI documentation, don't initiate printing directly from the page because the elements are optimized for interactive usage in a browser. diff --git a/layouts/partials/shortcodes/openapi.html b/layouts/partials/shortcodes/openapi.html index c62cf5bb29..e290f5539d 100644 --- a/layouts/partials/shortcodes/openapi.html +++ b/layouts/partials/shortcodes/openapi.html @@ -3,16 +3,27 @@ {{- $page = .context }} {{- warnf "%q: DEPRECATED parameter 'context' for shortcode 'openapi' found, use 'page' instead; see https://mcshelby.github.io/hugo-theme-relearn/basics/migration#5180" $page.File.Filename }} {{- end }} -{{- $src := .src }} +{{- $u := urls.Parse .src }} +{{- $src := $u.String }} {{- $spec := "" }} {{- $id := cond (or (eq .id nil) (eq .id "")) (partial "make-random-md5.hugo" $page) .id }} -{{- with $page }} -{{- with or - (.Resources.Get $src) - (resources.Get $src) -}} - {{- $spec = .Content }} +{{- if not $u.IsAbs }} + {{- $path := strings.TrimPrefix "./" $u.Path }} + {{- with or + ($page.Resources.Get $path) + (resources.Get $path) + }} + {{- $src = "" }} + {{- $spec = .Content }} + {{- else }} + {{- if eq $page.Site.Params.openapi.errorlevel "warning" }} + {{- warnf "%q: OpenAPI spec link '%s' is not a resource but linked anyways" $page.File.Filename .url }} + {{- else if eq $page.Site.Params.openapi.errorlevel "error" }} + {{- errorf "%q: OpenAPI spec link '%s' is not a resource" $page.File.Filename .url }} + {{- end }} + {{- end }} {{- end }} +{{- with $page }}