diff --git a/content/en/functions/openapi3/Unmarshal.md b/content/en/functions/openapi3/Unmarshal.md new file mode 100644 index 000000000..50c793685 --- /dev/null +++ b/content/en/functions/openapi3/Unmarshal.md @@ -0,0 +1,76 @@ +--- +title: openapi3.Unmarshal +description: Unmarshals the given resource into an OpenAPI 3 document. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: openapi3.OpenAPIDocument + signatures: ['openapi3.Unmarshal RESOURCE'] +--- + +Use the `openapi3.Unmarshal` function with [global], [page], or [remote] resources. + +[global]: /getting-started/glossary/#global-resource +[page]: /getting-started/glossary/#page-resource +[remote]: /getting-started/glossary/#remote-resource +[OpenAPI]: https://www.openapis.org/ + +For example, to work with a remote [OpenAPI] defintion: + +```go-html-template +{{ $url := "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json" }} +{{ $api := "" }} +{{ with resources.GetRemote $url }} + {{ with .Err }} + {{ errorf "%s" . }} + {{ else }} + {{ $api = . | openapi3.Unmarshal }} + {{ end }} +{{ else }} + {{ errorf "Unable to get remote resource %q" $url }} +{{ end }} +``` + +To inspect the data structure: + +```go-html-template +
{{ debug.Dump $api }}
+``` + +To list the GET and POST operations for each of the API paths: + +```go-html-template +{{ range $path, $details := $api.Paths }} +

{{ $path }}

+
+ {{ with $details.Get }} +
GET
+
{{ .Summary }}
+ {{ end }} + {{ with $details.Post }} +
POST
+
{{ .Summary }}
+ {{ end }} +
+{{ end }} +``` + +Hugo renders this to: + + +```html +

/pets

+
+
GET
+
List all pets
+
POST
+
Create a pet
+
+

/pets/{petId}

+
+
GET
+
Info for a specific pet
+
+``` diff --git a/content/en/functions/openapi3/_index.md b/content/en/functions/openapi3/_index.md new file mode 100644 index 000000000..9b6aa9584 --- /dev/null +++ b/content/en/functions/openapi3/_index.md @@ -0,0 +1,12 @@ +--- +title: OpenAPI functions +linkTitle: openapi3 +description: Template functions to work with OpenAPI 3 definitions. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with OpenAPI 3 definitions.