Conditionally Excluding Properties from OpenAPI Specs

[balassit]

Problem Statement:

In our API definitions, we have enums and model properties where some values or attributes are intended for internal use only or are restricted to partner teams. These values and properties should be excluded from the OpenAPI specification generated for external users, while still being available in internal or partner-facing code generation.

Solution:

Introduce a compilation check to optionally skip rendering specified enum values or model properties based on visibility annotations. This approach will allow us to define visibility rules directly in the API schema, enabling conditional exclusion during OpenAPI spec generation or code emission.

Implementation:

Enhance the existing @visibility annotation (or introduce a similar annotation) to support compile time visibility rules.

tspconfig.yaml

compilerOptions:
  emit:
    - "@typespec/openapi3"
  options:
    "@typespec/openapi3":
      visibility: "external" # Define the audience: "external", "partner", or "internal"

main.tsp

enum DeploymentEnvironment {
  Production: "Production"; // Always included in all contexts
  Staging: "Staging"; // Always included in all contexts

  @visibility(["internal"]) // Visible only to internal teams
  Development: "Development";

  @visibility(["partner", "internal"]) // Visible to internal teams and specific partners, but not external customers
  QA: "QA";
}

model DataSource {
  sourceType: SourceType; // Always included in all contexts

  @visibility(["internal"]) // Marks this property as internal-only
  internalConfiguration: string;
}

Checklist

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.