Should we report it as an error for unresolved $ref or defer it to other definitions outside of the controller?

Can you add a test case to allow @api at controller class level to supply definitions so that they can be shared by multiple methods in the controller?

was talking with @nabdelgadir , I think the @api() decorator takes in a whole OpenAPI spec described by interface ControllerSpec, so if a user wants to provide the model schema, the spec should be sth like:

{
  components: {
    schemas: {
      Todo: {
        // The Todo schema
      }
    }
  },
  paths: {
    // some path spec refers to the Todo schema provided in the root level property 
    // `components`, instead of providing the definition in itself.
  }
}

I added a test in this commit, although I'm not sure it's what you meant. I thought that OpenAPI spec had shared definitions in #/components/schemas? Can you please provide an example of what you meant?

Edit: oops posted this before I saw Janny's comment

@jannyHou Good point. We already have the ability to define schema at @api level. With that in mind, what's the additional value to allow definitions? Is it just for full support of json schema?

@raymondfeng I think definitions is the way to add schema reference in the method level metadata, the reason is explained in Miroslav's comment: #2629 (comment).
@api() doesn't have that limitation :)

Schema references can be used at method level regardless where the target schema is provided. With this PR, we allow the target schema to be defined in two ways:

1. At @api level - inside components.schemas.<target>
2. Use definitions with $ref:

schema: {
  $ref: #/definitions/Todo,
  definitions: {/* ... */} // [raymond] I assume the schema definitions are going to be visible to other methods?
}

@raymondfeng Since the definition will become a part of #/components/schemas, they should be visible to other methods.

What I meant is to only have schemas at @api level for the controller class, not individual operations.