-
Notifications
You must be signed in to change notification settings - Fork 1.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat(openapi-v3): allow controller to reference models via openapispec #2898
Conversation
}); | ||
}); | ||
|
||
it('returns an empty object when it cannot find definition of referenced model', () => { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we report it as an error for unresolved $ref
or defer it to other definitions outside of the controller?
}, | ||
}); | ||
}); | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
}
}
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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 :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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:
- At
@api
level - insidecomponents.schemas.<target>
- Use
definitions
with$ref
:
schema: {
$ref: #/definitions/Todo,
definitions: {/* ... */} // [raymond] I assume the schema definitions are going to be visible to other methods?
}
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@raymondfeng Since the definition
will become a part of #/components/schemas
, they should be visible to other methods.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Overall LGTM, got a question and +1 to @raymondfeng's comments.
7e75867
to
e738d63
Compare
@@ -332,6 +333,66 @@ describe('controller spec', () => { | |||
expect(globalSchemas).to.be.empty(); | |||
}); | |||
|
|||
it('allows a class to provide definitions of referenced models through #/components/schemas', () => { | |||
@api({ | |||
paths: { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What I meant is to only have schemas at @api
level for the controller class, not individual operations.
0ccf8d2
to
8172c46
Compare
packages/openapi-v3/src/__tests__/integration/controller-spec.integration.ts
Outdated
Show resolved
Hide resolved
packages/openapi-v3/src/__tests__/integration/controller-spec.integration.ts
Show resolved
Hide resolved
packages/openapi-v3/src/__tests__/integration/controller-spec.integration.ts
Show resolved
Hide resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please squash all commits before landing.
3eec6a5
to
ea45a99
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice additions from @api()
decorator 💯
Controller methods can now reference model schema through OpenAPI spec without the need to use the `x-ts-type` extension. Co-authored-by: Miroslav Bajtoš <[email protected]>
ea45a99
to
656aed8
Compare
Closes #2629.
Controller methods can now reference model schema directly via OpenAPI spec and without using the
x-ts-type
extensionChecklist
👉 Read and sign the CLA (Contributor License Agreement) 👈
npm test
passes on your machinepackages/cli
were updatedexamples/*
were updated👉 Check out how to submit a PR 👈