Sie können festlegen, welche OpenAPI-Operationen als Dokumentationsseiten veröffentlicht werden und wie sie in der Navigation angezeigt werden. Das ist nützlich für interne Endpunkte, veraltete Operationen, Beta-Funktionen oder Endpunkte, die zwar per direkter URL erreichbar sein sollen, aber nicht über die Navigation auffindbar. Wenn Ihre Seiten aus einem OpenAPI-Dokument generiert werden, können Sie die Sichtbarkeit mit den Erweiterungen x-hidden und x-excluded steuern.

​
x-hidden

Die Erweiterung x-hidden erstellt eine Seite für einen Endpoint, blendet sie jedoch in der Navigation aus. Die Seite ist nur erreichbar, wenn man direkt ihre URL aufruft. Häufige Anwendungsfälle für x-hidden sind:
  • Endpoints, die Sie dokumentieren, aber nicht prominent machen möchten.
  • Seiten, auf die Sie aus anderen Inhalten verlinken.
  • Endpoints für bestimmte Benutzer.

​
x-excluded

Die Erweiterung x-excluded schließt einen Endpunkt vollständig aus Ihrer Dokumentation aus. Häufige Anwendungsfälle für x-excluded sind:
  • Endpunkte, die nur intern verwendet werden.
  • Veraltete Endpunkte, die Sie nicht dokumentieren möchten.
  • Beta-Funktionen, die noch nicht für die öffentliche Dokumentation bereit sind.

​
Implementierung

Fügen Sie die Erweiterung x-hidden oder x-excluded unter der HTTP-Methode in Ihrer OpenAPI-Spezifikation hinzu. Hier sind Beispiele dafür, wie jede Eigenschaft in einem OpenAPI-Schema für einen Endpoint und einen Webhook-Pfad verwendet wird. 
"paths": {
  "/plants": {
    "get": {
      "description": "Returns all plants from the store",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  },
  "/hidden_plants": {
    "get": {
      "x-hidden": true,
      "description": "Returns all somewhat secret plants from the store",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  },
  "/secret_plants": {
    "get": {
      "x-excluded": true,
      "description": "Returns all top secret plants from the store (do not publish this endpoint!)",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  }
},

"webhooks": {
  "/plants_hook": {
    "post": {
      "description": "Webhook for information about a new plant added to the store",
    }
  },
  "/hidden_plants_hook": {
    "post": {
      "x-hidden": true,
      "description": "Webhook for somewhat secret information about a new plant added to the store"
    }
  },
  "/secret_plants_hook": {
    "post": {
      "x-excluded": true,
      "description": "Webhook for top secret information about a new plant added to the store (do not publish this endpoint!)"
    }
  }
}