Merge pull request #47 from fraunhoferfokus/main

* add elements viewer

Justfile

@@ -27,8 +27,9 @@ test:
 	go test ./... -v
 
 # Update required tools and libraries
-update: download-rapidoc download-style
+update: download-rapidoc download-elements download-style
     go get -u
+    go mod tidy
 
 # Install additionally required tools
 tools:
@@ -37,7 +38,12 @@ tools:
 
 # Download rapidoc, an OpenAPI documentation viewer
 download-rapidoc:
-    curl -o templates/web/css/rapidoc-min.js -L https://unpkg.com/rapidoc/dist/rapidoc-min.js
+    curl -o templates/web/js/rapidoc-min.js -L https://unpkg.com/rapidoc/dist/rapidoc-min.js
+
+# Download elements, an OpenAPI documentation viewer (https://stoplight.io/open-source/elements)
+download-elements:
+    curl -o templates/web/js/elements.min.js -L https://unpkg.com/@stoplight/elements/web-components.min.js
+    curl -o templates/web/css/elements.min.css -L https://unpkg.com/@stoplight/elements/styles.min.css
 
 # Download frontend libraries
 # woff Dateien müssen aus dem ZIP manuell nach fonts/ kopiert werden!

README.md

@@ -53,6 +53,7 @@ Generation flags:
 For typical tasks you can use the [just](https://just.systems/man/en/) recipes:
 
     build              # Build the local dredger binary
+    download-elements  # Download elements, an OpenAPI documentation viewer
     download-rapidoc   # Download rapidoc, an OpenAPI documentation viewer
     download-style     # Download frontend libraries
     generate           # Generate the source code in the target directory ./src from the OpenAPI file provided in the environment variable OPEN_API_PATH

core/version

@@ -1 +1 @@
-0.3.5
+0.3.6

generator/frontend.go

@@ -53,8 +53,9 @@ func generateFrontend(spec *openapi3.T, conf GeneratorConfig) {
 	fs.CopyWebFile("web/js", javascriptPath, "htmx-sse.js", true)
 	fs.CopyWebFile("web/js", javascriptPath, "htmx.min.js", true)
 	fs.CopyWebFile("web/js", javascriptPath, "hyperscript.js", true)
-	fs.CopyWebFile("web/js", javascriptPath, "rapidoc-min.js", true)
 	fs.CopyWebFile("web/js", javascriptPath, "sse.js", true)
+	fs.CopyWebFile("web/js", javascriptPath, "rapidoc-min.js", true)
+	fs.CopyWebFile("web/js", javascriptPath, "elements.min.js", true)
 
 	// files in stylesheet directory
 	fs.CopyWebFile("web/css", stylesheetPath, "bootstrap-icons.min.css", true)
@@ -63,7 +64,7 @@ func generateFrontend(spec *openapi3.T, conf GeneratorConfig) {
 	fs.CopyWebFile("web/css", stylesheetPath, "bootstrap.min.css", true)
 	fs.CopyWebFile("web/css", stylesheetPath, "pico.min.css", true)
 	fs.CopyWebFile("web/css", stylesheetPath, "pico.colors.min.css", true)
-	fs.CopyWebFile("web/css", stylesheetPath, "simple.min.css", true)
+	fs.CopyWebFile("web/css", stylesheetPath, "elements.min.css", true)
 
 	// files in images directory
 	fs.CopyWebFile("web/images", imagesPath, "favicon.ico", false)
@@ -224,7 +225,8 @@ func generateOpenAPIDoc(conf GeneratorConfig) {
 	}
 
 	// create static html files
-	createFileFromTemplate(filepath.Join(path, "index.html"), "templates/openapidoc/index.html.tmpl", template)
+	createFileFromTemplate(filepath.Join(path, "rapidoc.html"), "templates/rapidoc/index.html.tmpl", template)
+	createFileFromTemplate(filepath.Join(path, "elements.html"), "templates/elements/index.html.tmpl", template)
 
 	// copy OpenAPI Specification in this directory
 	fs.CopyFile(conf.OpenAPIPath, path, template.OpenAPIFile)

go.mod

@@ -32,10 +32,10 @@ require (
 	github.com/spf13/cast v1.7.0 // indirect
 	github.com/valyala/bytebufferpool v1.0.0 // indirect
 	github.com/valyala/fasttemplate v1.2.2 // indirect
-	golang.org/x/crypto v0.27.0 // indirect
+	golang.org/x/crypto v0.28.0 // indirect
 	golang.org/x/net v0.24.0 // indirect
 	golang.org/x/sync v0.8.0 // indirect
-	golang.org/x/text v0.18.0 // indirect
+	golang.org/x/text v0.19.0 // indirect
 )
 
 require (
@@ -53,6 +53,6 @@ require (
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/otiai10/copy v1.14.0
 	github.com/spf13/pflag v1.0.5 // indirect
-	golang.org/x/sys v0.25.0 // indirect
+	golang.org/x/sys v0.26.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -281,8 +281,8 @@ golang.org/x/crypto v0.0.0-20181029021203-45a5f77698d3/go.mod h1:6SG95UA2DQfeDnf
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20190510104115-cbcb75029529/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20190605123033-f99c8df09eb5/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
-golang.org/x/crypto v0.27.0 h1:GXm2NjJrPaiv/h1tb2UH8QfgC/hOf/+z0p6PT8o1w7A=
-golang.org/x/crypto v0.27.0/go.mod h1:1Xngt8kV6Dvbssa53Ziq6Eqn0HqbZi5Z6R0ZpwQzt70=
+golang.org/x/crypto v0.28.0 h1:GBDwsMXVQi34v5CCYUm2jkJvu4cbtru2U4TN2PSyQnw=
+golang.org/x/crypto v0.28.0/go.mod h1:rmgy+3RHxRZMyY0jjAJShp2zgEdOqj2AO7U0pYmeQ7U=
 golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
 golang.org/x/exp v0.0.0-20190306152737-a1d7652674e8/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
 golang.org/x/exp v0.0.0-20190510132918-efd6b22b2522/go.mod h1:ZjyILWgesfNpC6sMxTJOJm9Kp84zZh5NQWvqDGG3Qr8=
@@ -343,13 +343,13 @@ golang.org/x/sys v0.0.0-20190624142023-c5567b49c5d0/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.25.0 h1:r+8e+loiHxRqhXVl6ML1nO3l1+oFoWbnlu2Ehimmi34=
-golang.org/x/sys v0.25.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.26.0 h1:KHjCJyddX0LoSTb3J+vWpupP9p0oznkqVk/IfjymZbo=
+golang.org/x/sys v0.26.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.1-0.20180807135948-17ff2d5776d2/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
-golang.org/x/text v0.18.0 h1:XvMDiNzPAl0jr17s6W9lcaIhGUfUORdGCNsuLmPG224=
-golang.org/x/text v0.18.0/go.mod h1:BuEKDfySbSR4drPmRPG/7iBdf8hvFMuRexcpahXilzY=
+golang.org/x/text v0.19.0 h1:kTxAhCbGbxhK0IwgSKiMO5awPoDQ0RpfiVYBfK860YM=
+golang.org/x/text v0.19.0/go.mod h1:BuEKDfySbSR4drPmRPG/7iBdf8hvFMuRexcpahXilzY=
 golang.org/x/time v0.0.0-20181108054448-85acf8d2951c/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
 golang.org/x/time v0.0.0-20190308202827-9d24e82272b4/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
 golang.org/x/tools v0.0.0-20180221164845-07fd8470d635/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=

templates/core/config.go.tmpl

@@ -39,6 +39,8 @@ type Config struct {
 	Languages           []string `default:"en,de"`
 	UseSse              bool     `default:"false" split_words:"true"`
 	ProgressDuration    int      `default:"100" split_words:"true"`
+	RapidocDoc          bool     `default:"false" split_words:"true"`
+	ElementsDoc         bool     `default:"false" split_words:"true"`
 	ConfigExt
 }
 

templates/elements/index.html.tmpl

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+    <title>{{.ModuleName}} Frontend</title>
+
+    <script src="js/elements.min.js"></script>
+    <link rel="stylesheet" href="css/elements.min.css">
+  </head>
+  <body>
+
+    <elements-api
+      apiDescriptionUrl="{{.OpenAPIFile}}"
+      layout="responsive"
+      router="hash"
+    />
+
+  </body>
+</html>

templates/main.go.tmpl

@@ -62,8 +62,13 @@ func main() {
 	{{- if .AddFrontend }}
 
 	// serve doc
-	e.FileFS("/doc", "web/doc/index.html", embeddedFS)
+	if core.AppConfig.ElementsDoc {
+	   e.FileFS("/doc", "web/doc/elements.html", embeddedFS)
+	} else if core.AppConfig.RapidocDoc {
+	   e.FileFS("/doc", "web/doc/rapidoc.html", embeddedFS)
+	}
 	e.FileFS("/{{.OpenAPIName}}.yaml", "web/doc/{{.OpenAPIName}}.yaml", embeddedFS)
+
 	// serve default stylesheets and javascript files
 	e.StaticFS("/css/", echo.MustSubFS(web.Css, "css"))
 	e.StaticFS("/js/", echo.MustSubFS(web.Js, "js"))

templates/web/js/htmx-sse.js

@@ -7,15 +7,20 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 
 (function() {
 
+	if (htmx.version && !htmx.version.startsWith("1.")) {
+		console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version +
+			".  It is recommended that you move to the version of this extension found on https://htmx.org/extensions")
+	}
+
 	/** @type {import("../htmx").HtmxInternalApi} */
 	var api;
 
 	htmx.defineExtension("sse", {
 
 		/**
 		 * Init saves the provided reference to the internal HTMX API.
-		 * 
-		 * @param {import("../htmx").HtmxInternalApi} api 
+		 *
+		 * @param {import("../htmx").HtmxInternalApi} api
 		 * @returns void
 		 */
 		init: function(apiRef) {
@@ -30,9 +35,9 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 
 		/**
 		 * onEvent handles all events passed to this extension.
-		 * 
-		 * @param {string} name 
-		 * @param {Event} evt 
+		 *
+		 * @param {string} name
+		 * @param {Event} evt
 		 * @returns void
 		 */
 		onEvent: function(name, evt) {
@@ -64,8 +69,8 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 	/**
 	 * createEventSource is the default method for creating new EventSource objects.
 	 * it is hoisted into htmx.config.createEventSource to be overridden by the user, if needed.
-	 * 
-	 * @param {string} url 
+	 *
+	 * @param {string} url
 	 * @returns EventSource
 	 */
 	function createEventSource(url) {
@@ -105,7 +110,7 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 	}
 
 	/**
-	 * registerSSE looks for attributes that can contain sse events, right 
+	 * registerSSE looks for attributes that can contain sse events, right
 	 * now hx-trigger and sse-swap and adds listeners based on these attributes too
 	 * the closest event source
 	 *
@@ -183,7 +188,7 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 			if (sseEventName.slice(0, 4) != "sse:") {
 				return;
 			}
-			
+
 			// remove the sse: prefix from here on out
 			sseEventName = sseEventName.substr(4);
 
@@ -269,8 +274,8 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 	/**
 	 * maybeCloseSSESource confirms that the parent element still exists.
 	 * If not, then any associated SSE source is closed and the function returns true.
-	 * 
-	 * @param {HTMLElement} elt 
+	 *
+	 * @param {HTMLElement} elt
 	 * @returns boolean
 	 */
 	function maybeCloseSSESource(elt) {
@@ -287,9 +292,9 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 
 	/**
 	 * queryAttributeOnThisOrChildren returns all nodes that contain the requested attributeName, INCLUDING THE PROVIDED ROOT ELEMENT.
-	 * 
-	 * @param {HTMLElement} elt 
-	 * @param {string} attributeName 
+	 *
+	 * @param {HTMLElement} elt
+	 * @param {string} attributeName
 	 */
 	function queryAttributeOnThisOrChildren(elt, attributeName) {
 
@@ -310,7 +315,7 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 
 	/**
 	 * @param {HTMLElement} elt
-	 * @param {string} content 
+	 * @param {string} content
 	 */
 	function swap(elt, content) {
 
@@ -340,10 +345,10 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 	}
 
 	/**
-	 * doSettle mirrors much of the functionality in htmx that 
+	 * doSettle mirrors much of the functionality in htmx that
 	 * settles elements after their content has been swapped.
 	 * TODO: this should be published by htmx, and not duplicated here
-	 * @param {import("../htmx").HtmxSettleInfo} settleInfo 
+	 * @param {import("../htmx").HtmxSettleInfo} settleInfo
 	 * @returns () => void
 	 */
 	function doSettle(settleInfo) {

templates/web/js/sse.js

@@ -7,15 +7,20 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 
 (function() {
 
+	if (htmx.version && !htmx.version.startsWith("1.")) {
+		console.warn("WARNING: You are using an htmx 1 extension with htmx " + htmx.version +
+			".  It is recommended that you move to the version of this extension found on https://htmx.org/extensions")
+	}
+
 	/** @type {import("../htmx").HtmxInternalApi} */
 	var api;
 
 	htmx.defineExtension("sse", {
 
 		/**
 		 * Init saves the provided reference to the internal HTMX API.
-		 * 
-		 * @param {import("../htmx").HtmxInternalApi} api 
+		 *
+		 * @param {import("../htmx").HtmxInternalApi} api
 		 * @returns void
 		 */
 		init: function(apiRef) {
@@ -30,9 +35,9 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 
 		/**
 		 * onEvent handles all events passed to this extension.
-		 * 
-		 * @param {string} name 
-		 * @param {Event} evt 
+		 *
+		 * @param {string} name
+		 * @param {Event} evt
 		 * @returns void
 		 */
 		onEvent: function(name, evt) {
@@ -64,8 +69,8 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 	/**
 	 * createEventSource is the default method for creating new EventSource objects.
 	 * it is hoisted into htmx.config.createEventSource to be overridden by the user, if needed.
-	 * 
-	 * @param {string} url 
+	 *
+	 * @param {string} url
 	 * @returns EventSource
 	 */
 	function createEventSource(url) {
@@ -105,7 +110,7 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 	}
 
 	/**
-	 * registerSSE looks for attributes that can contain sse events, right 
+	 * registerSSE looks for attributes that can contain sse events, right
 	 * now hx-trigger and sse-swap and adds listeners based on these attributes too
 	 * the closest event source
 	 *
@@ -183,7 +188,7 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 			if (sseEventName.slice(0, 4) != "sse:") {
 				return;
 			}
-			
+
 			// remove the sse: prefix from here on out
 			sseEventName = sseEventName.substr(4);
 
@@ -269,8 +274,8 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 	/**
 	 * maybeCloseSSESource confirms that the parent element still exists.
 	 * If not, then any associated SSE source is closed and the function returns true.
-	 * 
-	 * @param {HTMLElement} elt 
+	 *
+	 * @param {HTMLElement} elt
 	 * @returns boolean
 	 */
 	function maybeCloseSSESource(elt) {
@@ -287,9 +292,9 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 
 	/**
 	 * queryAttributeOnThisOrChildren returns all nodes that contain the requested attributeName, INCLUDING THE PROVIDED ROOT ELEMENT.
-	 * 
-	 * @param {HTMLElement} elt 
-	 * @param {string} attributeName 
+	 *
+	 * @param {HTMLElement} elt
+	 * @param {string} attributeName
 	 */
 	function queryAttributeOnThisOrChildren(elt, attributeName) {
 
@@ -310,7 +315,7 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 
 	/**
 	 * @param {HTMLElement} elt
-	 * @param {string} content 
+	 * @param {string} content
 	 */
 	function swap(elt, content) {
 
@@ -340,10 +345,10 @@ This extension adds support for Server Sent Events to htmx.  See /www/extensions
 	}
 
 	/**
-	 * doSettle mirrors much of the functionality in htmx that 
+	 * doSettle mirrors much of the functionality in htmx that
 	 * settles elements after their content has been swapped.
 	 * TODO: this should be published by htmx, and not duplicated here
-	 * @param {import("../htmx").HtmxSettleInfo} settleInfo 
+	 * @param {import("../htmx").HtmxSettleInfo} settleInfo
 	 * @returns () => void
 	 */
 	function doSettle(settleInfo) {