# `WardrikRest.OpenAPI`

Reads OpenAPI 3.0 and 3.1 documents, in JSON or YAML.

    {:ok, suggestions} =
      WardrikRest.API.load(
        {WardrikRest.OpenAPI, path: "priv/apis/catalog-suggestion.openapi.yaml"},
        name: "meta_catalog",
        base_url: "https://ads-api.facebook.com/v27.0/marketing-api",
        auth: %{"OAuthToken__Authorization" => {:credential, "meta"}}
      )

## Options

  * `:url` - where the document is. `:req_options` are merged into its request.
  * `:path` - a file holding it.
  * `:document` - the document itself, decoded.

## How it reads

  * Each operation is named by its `operationId`, any character but a letter, a digit or `_`
    made `_`, or by its method and path where it has none.
  * Its path, query and header parameters become arguments; cookie parameters are left out.
  * A JSON body's fields become arguments beside them, and a field named like a parameter is
    left out. A body that isn't an object of fields is one argument, `body`. An
    `application/x-www-form-urlencoded` body is sent form-encoded. An operation whose body is
    only some other type, as a file upload, is left out.
  * Its security, or the document's, gives its schemes: `http` `bearer`, `oauth2` and
    `openIdConnect` as a bearer token, and `apiKey` in a header or the query, each by its name
    in `components/securitySchemes`. An alternative needing any other scheme, as HTTP basic,
    is left out, and an operation with none left can't be offered.
  * `components/schemas` become the spec's types. See `WardrikRest.OpenAPI.Schema`.
  * Its `servers` are never read: the API's `:base_url` says where it's reached, with any path
    a server has, as `/v1`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*