no-openapi

Full name

@azure-tools/typespec-azure-core/no-openapi

Azure services should not be using decorators from the OpenAPIs libraries(@azure-tools/openapi, @azure-tools/typespec-autorest or @azure-tools/openapi3) in their spec. Using those decorators is usually a sign that the spec is either not following the correct Azure or trying to match exactly a particular OpenAPI spec which should be a non-goal.

Those decorators are only meant to be read by the openapi emitters which means this might achieve the correct OpenAPI output but other emitters(client SDK, service, etc.) will not be able to understand them and will see a broken representation of the spec.

Decorators and their alternatives

OpenAPI Decorator	Alternative
@example	See examples doc
@extension("x-ms-examples",	See examples doc
@extension("x-ms-client-flatten",	TCGC @flattenProperty
@extension("x-ms-mutability",	Use @visibility decorator
@extension("x-ms-enum",	Enum extensibility doc
@extension("x-ms-identifiers",	Use @identifiers
@operationId	Name your interface and operation accordingly
@useRef	This should not be used, define the types correctly in TypeSpec. For ARM common types read the Arm docs
@info	Use versioning library for version and @service for title

Examples

@extension("x-ms-enum"

❌ Incorrect

@extension(
  "x-ms-enum",
  {
    name: "PetKind",
    modelAsString: true,
  }
)
enum PetKind {
  Cat,
  Dog,
}

✅ Correct

union PetKind {
  Cat: "Cat",
  Dog: "Dog",
  string,
}

@extension("x-ms-mutability"

❌ Incorrect

model Pet {
  @extension("x-ms-mutability", #["read", "create"])
  name: string;
}

@extension("x-ms-identifiers"

❌ Incorrect

model Pet {
  @extension("x-ms-identifiers", #["customId"])
  names: Name[];
}
model Name {
  customId: string;
}

✅ Correct

model Pet {
  @identifiers(#["customId"])
  names: Name[];
}
model Name {
  customId: string;
}

@operationId

❌ Incorrect

@operationId("Pet_Get")
op getPet(): Pet;

✅ Correct

interface Pet {
  get(): Pet;
}