# OpenAPI

[OpenAPI][1] is a document that describes an API. It contains:

* at least one [paths][2] field.
* a [components][3] field or a [webhooks][4] field.

Media types should conform to [RFC-6838][5].
HTTP Status codes should follow [RFC-7231][6] and [IANA][7].

## Format

The document is a JSON file called `openapi.json`.

```json
{
  "field": [1, 2, 3]
}
```

* field names are case sensitive
* fields can be:
  * Fixed fields: have a declared name
  * Patterned fields: declare a regex pattern for the field name

Data Types

| type    | format   |
| ------- | -------- |
| integer | int32    |
| integer | int64    |
| number  | float    |
| number  | double   |
| string  | password |

Description fields can be written in [CommonMark][8] markdown.

Minimal example:

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "xlg API",
    "version": "0.1.0"
  },
  "servers": [
    {
      "url": "https://dev.xlg.c0/v0",
      "description": "dev api"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "responses": {
          "200": {
            "description": "Healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "security": {
    "type": "openIdConnect",
    "openIdConnectUrl": "https://xlg.auth0.com/.well-known/openid-configuration"
  }
}
```

[1]: https://spec.openapis.org/oas/v3.1.0#openapi-document
[2]: https://spec.openapis.org/oas/v3.1.0#pathsObject
[3]: https://spec.openapis.org/oas/v3.1.0#oasComponents
[4]: https://spec.openapis.org/oas/v3.1.0#oasWebhooks
[5]: https://www.rfc-editor.org/rfc/rfc6838.txt
[6]: https://www.rfc-editor.org/rfc/rfc7231.txt
[7]: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
[8]: https://spec.commonmark.org/0.30/