OpenAPI Documentation Settings

The OpenAPI 3.2 document and the Scalar reference at /docs are generated from the loaded endpoint files. SQL endpoints add column names and types read from the database at startup; other endpoint types use the Documentation block in entity.json.

Generated content ​

Global configuration ​

{
  "OpenApi": {
    "Enabled": true,
    "Title": "Portway: API Gateway",
    "Version": "v1",
    "Description": "Integration API for ERP and warehouse data.",
    "Contact": {
      "Name": "Your Name",
      "Email": "support@yourcompany.com"
    },
    "Footer": {
      "Text": "Powered by Portway",
      "Target": "_blank",
      "Url": "#"
    },
    "SecurityDefinition": {
      "Name": "Bearer",
      "Description": "Bearer token issued by Portway. Send it as: Authorization: Bearer {token}",
      "In": "Header",
      "Type": "Http",
      "Scheme": "Bearer"
    },
    "ShowBadges": true,
    "ExternalDocs": {
      "Url": "https://example.com/api-guide",
      "Description": "Integration guide"
    },
    "ScalarTheme": "default",
    "ScalarLayout": "modern",
    "ScalarShowSidebar": true,
    "ScalarHideDownloadButton": false,
    "ScalarHideModels": true,
    "ScalarHideClientButton": true,
    "ScalarHideTestRequestButton": false
  }
}

The console edits these properties under Settings → OpenAPI (/ui/settings#openapi: OpenAPI, API Reference and Reference Footer cards), except SecurityDefinition.Name, Type, In and Scheme: Portway accepts tokens only in the Authorization header. Enabled and SecurityDefinition.Description apply after a restart; the others apply on save. Version and DefaultGroup accept letters, digits, ., - and _. Footer.Url accepts http, https and mailto links or #. ExternalDocs.Url accepts http and https links or empty.

The document is served at /docs/openapi.json; /docs/openapi/v{n}/openapi.json holds the operations of one endpoint version. Other names under /docs/openapi/{name}/openapi.json redirect to /docs/openapi.json.

Every operation has a shareable URL under /docs (for example /docs/tag/...). Code samples cover curl (default), C#, JavaScript, Python and PowerShell.

Endpoint documentation ​

{
  "DatabaseObjectName": "Products",
  "AllowedColumns": ["ItemCode", "Description", "Price"],
  "Documentation": {
    "TagDescription": "**Product Catalog**\n\nAccess the product catalog with detailed item information.",
    "MethodDescriptions": {
      "GET": "Query product catalog with filtering and pagination",
      "POST": "Add new products to the catalog"
    },
    "Examples": {
      "GET": {
        "count": 1,
        "value": [
          { "ItemCode": "ITEM-001", "Description": "Widget", "Price": 9.99 }
        ]
      }
    }
  }
}

Descriptions support GitHub-flavoured Markdown, <br> and <p>, and Scalar alerts (> [!tip], Scalar markdown). Method keys match the endpoint's methods exactly.

Deprecated and disabled endpoints ​

With Deprecated: true, the endpoint's operations are marked deprecated and requests are served. DeprecatedSince and Sunset add response headers (Retiring a version).

{
  "DatabaseObjectName": "LegacyOrders",
  "AllowedMethods": ["GET"],
  "Deprecated": true
}

With Enabled: false, requests return 503 with Retry-After, the operations stay in the document as deprecated with a [Disabled] prefix, and the endpoint is removed from MCP. The change applies at the next configuration reload. Example: Static/Production/Machines.

{
  "success": false,
  "error": "This endpoint is temporarily disabled for scheduled maintenance."
}

Schema discovery ​

SQL column metadata is read at startup from the first environment in the endpoint's AllowedEnvironments.

Troubleshooting ​

Related topics ​

• Entity Configuration
• API Overview
• Namespaces