openapi3.Unmarshal

The resource passed to the openapi3.Unmarshal function must be an OpenAPI Document, typically in JSON or YAML format. This resource can be a global resource or a remote resource.

This function automatically resolves and includes all external references, both local and remote, and returns a complete OpenAPI Description that fully describes the surface of an API and its semantics.

Options

getremote

(map) This is a map of the options for the resources.GetRemote function, useful when an OpenAPI Document includes remote external references.

Examples

Remote resource

To work with a remote resource:

{{ $api := "" }}
{{ $url := "https://petstore.swagger.io/v2/swagger.json" }}
{{ $opts := dict
  "headers" (dict "Authorization" "Bearer abcd")
}}
{{ with try (resources.GetRemote $url $opts) }}
  {{ with .Err }}
    {{ errorf "%s" . }}
  {{ else with .Value }}
    {{ $api = openapi3.Unmarshal . (dict "getremote" $opts) }}
  {{ else }}
    {{ errorf "Unable to get remote resource %q" $url }}
  {{ end }}
{{ end }}

In the example above, the same HTTP Authorization header is used for both the initial remote request made by the resources.GetRemote function and for subsequent requests by the openapi.Unmarshal function as it retrieve remote external references.

Global resource

To work with a global resource:

{{ $api := "" }}
{{ $opts := dict
  "method" "post"
  "key" now.UnixNano
}}
{{ with resources.Get "api/petstore.json" }}
  {{ $api = openapi3.Unmarshal . (dict "getremote" $opts) }}
{{ end }}

For global resources, local external reference paths starting with / are resolved relative to the assets directory. All other local paths are resolved relative to the entry point. In the example above, local paths are resolved relative to assets/api/petstore.json.

Inspection

To inspect the unmarshaled data structure:

<pre>{{ debug.Dump $api }}</pre>

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

{{ range $path, $details := $api.Paths.Map }}
  <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:

<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>