no-openapi

@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
`@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

Exceptions

@extension("x-ms-identifiers" is allowed as this right now has no alternative and is an ARM requirement that is not used by any other emitter.

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;
}

✅ Correct

model Pet {
  @visibility(Lifecycle.Read, Lifecycle.Create)
  name: string;
}

`@operationId`

❌ Incorrect

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

✅ Correct

interface Pet {
  get(): Pet;
}