aboutsummaryrefslogtreecommitdiffhomepage
path: root/docs/content/en/functions/openapi3/Unmarshal.md
blob: 433337aefbf100b9447b3bf3434cbc9f4364611c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
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] definition:

```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
<pre>{{ debug.Dump $api }}</pre>
```

To list the GET and POST operations for each of the API paths:

```go-html-template
{{ range $path, $details := $api.Paths }}
  <p>{{ $path }}</p>
  <dl>
    {{ with $details.Get }}
      <dt>GET</dt>
      <dd>{{ .Summary }}</dd>
    {{ end }}
    {{ with $details.Post }}
      <dt>POST</dt>
      <dd>{{ .Summary }}</dd>
    {{ end }}
  </dl>
{{ end }}
```

Hugo renders this to:


```html
<p>/pets</p>
<dl>
  <dt>GET</dt>
  <dd>List all pets</dd>
  <dt>POST</dt>
  <dd>Create a pet</dd>
</dl>
<p>/pets/{petId}</p>
<dl>
  <dt>GET</dt>
  <dd>Info for a specific pet</dd>
</dl>
```