# /sys/internal/specs/openapi

The `/sys/internal/specs/openapi` endpoint is used to generate an OpenAPI document of the mounted backends. The response conforms to the [OpenAPI V3 specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md), with path names matching the mount names used by the Vault server (i.e. customizations with `-path` will be reflected). The set of included paths is based on the permissions of the request token.

The response may include Vault-specific [extensions](https://github.com/oai/openapi-specification/blob/master/versions/3.0.2.md#specification-extensions). Three are currently defined:

* `x-vault-sudo` - Endpoint requires sudo privileges.
* `x-vault-unauthenticated` - Endpoint is unauthenticated.
* `x-vault-create-supported` - Endpoint allows creation of new items, in addition to updating existing items.

Basic documentation will be generated for all paths, but a newer path definition structure now allows for more detailed documentation to be added. At this time the `/sys` endpoints have been updated to use the new structure, and other endpoints will be modified incrementally.

### Get OpenAPI document

This endpoint returns a single OpenAPI document describing all paths visible to the requester.

| Method | Path                          |
| ------ | ----------------------------- |
| `GET`  | `/sys/internal/specs/openapi` |

#### Parameters

* `generic_mount_paths` `(bool: false)` – Used to specify whether to use generic mount paths. If set, the mount paths will be replaced with a dynamic parameter: `{mountPath}`

#### Sample request

```shell-session
$ curl http://127.0.0.1:8200/v1/sys/internal/specs/openapi?generic_mount_paths=false
```

#### Sample response

```json
{
  "openapi": "3.0.2",
  "info": {
    "title": "HashiCorp Vault API",
    "description": "HTTP API that gives you full access to Vault. All API routes are prefixed with `/v1/`.",
    "version": "1.0.0",
    "license": {
      "name": "Mozilla Public License 2.0",
      "url": "https://www.mozilla.org/en-US/MPL/2.0"
    }
  },
  "paths": {
    "/auth/token/create": {
      "description": "The token create path is used to create new tokens.",
      "post": {
        "summary": "The token create path is used to create new tokens.",
        "tags": [
          "auth"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    ...
```