feat: add 'Query' derive to manage custom Utoipa Query descriptions #1890
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Reviewer's GuideThis PR introduces a custom derive macro and a wrapper type to automate generation of EBNF-based query and sort parameter descriptions, replaces manual grammar entries in the OpenAPI spec, and integrates these into advisory and vulnerability endpoints, alongside necessary workspace configuration updates. Entity relationship diagram for query parameter field mappingerDiagram
ADVISORY_QUERY {
UUID id
STRING identifier
STRING version
STRING document_id
BOOL deprecated
UUID issuer_id
DATETIME published
DATETIME modified
DATETIME withdrawn
STRING title
DATETIME ingested
STRING label
}
VULNERABILITY_QUERY {
STRING id
STRING title
DATETIME reserved
DATETIME published
DATETIME modified
DATETIME withdrawn
STRING[] cwes
FLOAT base_score
SEVERITY base_severity
}
ADVISORY_QUERY ||--o{ TrustifyQuery : "used as T"
VULNERABILITY_QUERY ||--o{ TrustifyQuery : "used as T"
Class diagram for the new Query derive macro and TrustifyQuery wrapperclassDiagram
class Query {
<<trait>>
+generate_query_description() String
+generate_sort_description() String
}
class TrustifyQuery~T: Query~ {
-phantom: PhantomData<T>
}
TrustifyQuery ..|> IntoParams
TrustifyQuery ..|> Query
class IntoParams {
<<trait>>
+into_params(parameter_in_provider) Vec<Parameter>
}
Query <|.. TrustifyQuery
IntoParams <|.. TrustifyQuery
class Query_derive_macro {
<<proc-macro derive(Query)>>
// Implements Query for struct
}
Query_derive_macro ..> Query : implements
Class diagram for AdvisoryQuery and VulnerabilityQuery usageclassDiagram
class AdvisoryQuery {
+id: Uuid
+identifier: String
+version: Option<String>
+document_id: String
+deprecated: bool
+issuer_id: Option<Uuid>
+published: Option<OffsetDateTime>
+modified: Option<OffsetDateTime>
+withdrawn: Option<OffsetDateTime>
+title: Option<String>
+ingested: OffsetDateTime
+label: String
}
AdvisoryQuery ..|> Query
class VulnerabilityQuery {
+id: String
+title: Option<String>
+reserved: Option<OffsetDateTime>
+published: Option<OffsetDateTime>
+modified: Option<OffsetDateTime>
+withdrawn: Option<OffsetDateTime>
+cwes: Option<Vec<String>>
+base_score: Option<f64>
+base_severity: Option<Severity>
}
VulnerabilityQuery ..|> Query
class TrustifyQuery~T: Query~
TrustifyQuery <.. AdvisoryQuery : used as T
TrustifyQuery <.. VulnerabilityQuery : used as T
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Codecov ReportAttention: Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #1890 +/- ##
==========================================
+ Coverage 68.06% 68.25% +0.19%
==========================================
Files 365 367 +2
Lines 23063 23211 +148
Branches 23063 23211 +148
==========================================
+ Hits 15698 15843 +145
- Misses 6486 6488 +2
- Partials 879 880 +1 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
jcrossley3
reviewed
Jul 22, 2025
Comment on lines
58
to
66
| #[allow(dead_code)] | ||
| #[derive(QueryDoc)] | ||
| struct AdvisoryQuery { | ||
| average_score: i32, | ||
| average_severity: String, | ||
| modified: Date, | ||
| title: String, | ||
| } | ||
|
|
There was a problem hiding this comment.
Suggested change
| #[allow(dead_code)] | |
| #[derive(QueryDoc)] | |
| struct AdvisoryQuery { | |
| average_score: i32, | |
| average_severity: String, | |
| modified: Date, | |
| title: String, | |
| } | |
| /// List advisories | |
| /// | |
| /// Valid field names to use in sort/filter queries: | |
| /// - average_score | |
| /// - average_severity | |
| /// - modified | |
| /// - title | |
| /// |
There was a problem hiding this comment.
The goal is to have a customized OpenAPI description for each endpoint similar to the detailed (but hardcoded) EBNF grammar definition (without having to copy & paste the same grammar in each endpoint) currently available in
trustify/common/src/db/query.rs
Lines 141 to 210 in ecc14e8
Considering only this PR will have all of the derive procedural macro code, the changes required for using it will be just a matter of defining a struct with the list of fields, the same list you have in the proposed comment but with the benefit of being able to further improve/manage it in the future as we need.
Comment on lines
33
to
41
| #[allow(dead_code)] | ||
| #[derive(QueryDoc)] | ||
| struct VulnerabilityQuery { | ||
| base_score: i32, | ||
| base_severity: String, | ||
| modified: Date, | ||
| title: String, | ||
| } | ||
|
|
There was a problem hiding this comment.
Suggested change
| #[allow(dead_code)] | |
| #[derive(QueryDoc)] | |
| struct VulnerabilityQuery { | |
| base_score: i32, | |
| base_severity: String, | |
| modified: Date, | |
| title: String, | |
| } | |
| /// List vulnerabilities | |
| /// | |
| /// Valid field names to use in sort/filter queries: | |
| /// - base_score | |
| /// - base_severity | |
| /// - modified | |
| /// - title | |
| /// |
ctron
reviewed
Jul 23, 2025
Cool, I've renamed it 👍 |
|
If this is purely to add in common docs, can you use something like on each operation to amend additional docs? ref: https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html |
This PR is more about having a documentation template (i.e. the EBNF grammar) populated with custom fields each endpoint manages providing a solution that allows us to further improve it. |
|
@sourcery-ai summary |
mrizzi
force-pushed
the
feat-macro-generate-openapi
branch
from
f7302a4 to
ed3e90b
Compare
mrizzi
changed the title
jcrossley3
reviewed
Jul 23, 2025
Signed-off-by: mrizzi <[email protected]>
Signed-off-by: mrizzi <[email protected]>
mrizzi
force-pushed
the
feat-macro-generate-openapi
branch
from
ed3e90b to
5d6172d
Compare
Signed-off-by: mrizzi <[email protected]>
mrizzi
force-pushed
the
feat-macro-generate-openapi
branch
from
d7d2603 to
78bde90
Compare
|
@sourcery-ai summary |
|
@sourcery-ai review |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey @mrizzi - I've reviewed your changes and they look great!
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location> `query/query-derive/src/lib.rs:16` </location>
<code_context>
+
+fn impl_query(ast: &syn::DeriveInput) -> TokenStream {
+ let name = &ast.ident;
+ let fields = match &ast.data {
+ Data::Struct(data_struct) => data_struct
+ .fields
+ .clone()
+ .into_iter()
+ .map(|field| match field.ident {
+ Some(ref ident) => ident.to_string(),
+ None => String::default(),
+ })
+ .collect::<Vec<String>>(),
+ Data::Enum(_) => vec![],
+ Data::Union(_) => vec![],
+ };
</code_context>
<issue_to_address>
The macro currently ignores tuple and unnamed struct fields.
If tuple structs aren't supported, add a compile error or explicit panic to prevent silent failures.
</issue_to_address>
<suggested_fix>
<<<<<<< SEARCH
fn impl_query(ast: &syn::DeriveInput) -> TokenStream {
let name = &ast.ident;
let fields = match &ast.data {
Data::Struct(data_struct) => data_struct
.fields
.clone()
.into_iter()
.map(|field| match field.ident {
Some(ref ident) => ident.to_string(),
None => String::default(),
})
.collect::<Vec<String>>(),
Data::Enum(_) => vec![],
Data::Union(_) => vec![],
};
=======
fn impl_query(ast: &syn::DeriveInput) -> TokenStream {
let name = &ast.ident;
let fields = match &ast.data {
Data::Struct(data_struct) => {
match &data_struct.fields {
syn::Fields::Named(fields_named) => {
fields_named.named.iter()
.map(|field| field.ident.as_ref().unwrap().to_string())
.collect::<Vec<String>>()
}
syn::Fields::Unnamed(_) | syn::Fields::Unit => {
return syn::Error::new_spanned(
&ast.ident,
"Tuple structs and unit structs are not supported by #[derive(QueryDoc)]"
)
.to_compile_error()
.into();
}
}
}
Data::Enum(_) => vec![],
Data::Union(_) => vec![],
};
>>>>>>> REPLACE
</suggested_fix>
### Comment 2
<location> `query/query-derive/src/lib.rs:69` </location>
<code_context>
+ );
+
+ let generated = quote! {
+ impl query::Query for #name {
+ fn generate_query_description() -> String {
+ #query_description.to_string()
</code_context>
<issue_to_address>
The macro assumes the `query` crate is always imported as `query`.
If `query` is renamed or missing, this will fail. Use `$crate` or document the required import path.
</issue_to_address>
<suggested_fix>
<<<<<<< SEARCH
let generated = quote! {
impl query::Query for #name {
fn generate_query_description() -> String {
#query_description.to_string()
}
fn generate_sort_description() -> String {
#sort_description.to_string()
}
}
};
=======
let generated = quote! {
impl $crate::Query for #name {
fn generate_query_description() -> String {
#query_description.to_string()
}
fn generate_sort_description() -> String {
#sort_description.to_string()
}
}
};
>>>>>>> REPLACE
</suggested_fix>
### Comment 3
<location> `modules/fundamental/src/advisory/endpoints/mod.rs:60` </location>
<code_context>
}
+#[allow(dead_code)]
+#[derive(Query)]
+struct AdvisoryQuery {
+ id: Uuid,
+ identifier: String,
+ version: Option<String>,
+ document_id: String,
+ deprecated: bool,
+ issuer_id: Option<Uuid>,
+ published: Option<OffsetDateTime>,
+ modified: Option<OffsetDateTime>,
+ withdrawn: Option<OffsetDateTime>,
+ title: Option<String>,
+ ingested: OffsetDateTime,
+ label: String,
+}
+
</code_context>
<issue_to_address>
The AdvisoryQuery struct uses non-Option types for some fields, which may not match query parameter semantics.
Since these fields are not Option types, they must always be provided, which may not align with how query parameters are typically used. This could lead to deserialization errors if any of these fields are missing in incoming queries.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Comment on lines
+14
to
+28
| fn impl_query(ast: &syn::DeriveInput) -> TokenStream { | ||
| let name = &ast.ident; | ||
| let fields = match &ast.data { | ||
| Data::Struct(data_struct) => data_struct | ||
| .fields | ||
| .clone() | ||
| .into_iter() | ||
| .map(|field| match field.ident { | ||
| Some(ref ident) => ident.to_string(), | ||
| None => String::default(), | ||
| }) | ||
| .collect::<Vec<String>>(), | ||
| Data::Enum(_) => vec![], | ||
| Data::Union(_) => vec![], | ||
| }; |
There was a problem hiding this comment.
suggestion (bug_risk): The macro currently ignores tuple and unnamed struct fields.
If tuple structs aren't supported, add a compile error or explicit panic to prevent silent failures.
Suggested change
| fn impl_query(ast: &syn::DeriveInput) -> TokenStream { | |
| let name = &ast.ident; | |
| let fields = match &ast.data { | |
| Data::Struct(data_struct) => data_struct | |
| .fields | |
| .clone() | |
| .into_iter() | |
| .map(|field| match field.ident { | |
| Some(ref ident) => ident.to_string(), | |
| None => String::default(), | |
| }) | |
| .collect::<Vec<String>>(), | |
| Data::Enum(_) => vec![], | |
| Data::Union(_) => vec![], | |
| }; | |
| fn impl_query(ast: &syn::DeriveInput) -> TokenStream { | |
| let name = &ast.ident; | |
| let fields = match &ast.data { | |
| Data::Struct(data_struct) => { | |
| match &data_struct.fields { | |
| syn::Fields::Named(fields_named) => { | |
| fields_named.named.iter() | |
| .map(|field| field.ident.as_ref().unwrap().to_string()) | |
| .collect::<Vec<String>>() | |
| } | |
| syn::Fields::Unnamed(_) | syn::Fields::Unit => { | |
| return syn::Error::new_spanned( | |
| &ast.ident, | |
| "Tuple structs and unit structs are not supported by #[derive(QueryDoc)]" | |
| ) | |
| .to_compile_error() | |
| .into(); | |
| } | |
| } | |
| } | |
| Data::Enum(_) => vec![], | |
| Data::Union(_) => vec![], | |
| }; |
Comment on lines
+60
to
+69
| #[derive(Query)] | ||
| struct AdvisoryQuery { | ||
| id: Uuid, | ||
| identifier: String, | ||
| version: Option<String>, | ||
| document_id: String, | ||
| deprecated: bool, | ||
| issuer_id: Option<Uuid>, | ||
| published: Option<OffsetDateTime>, | ||
| modified: Option<OffsetDateTime>, |
There was a problem hiding this comment.
issue (bug_risk): The AdvisoryQuery struct uses non-Option types for some fields, which may not match query parameter semantics.
Since these fields are not Option types, they must always be provided, which may not align with how query parameters are typically used. This could lead to deserialization errors if any of these fields are missing in incoming queries.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Implementing the
QueryDoccustomDerivemacro in order to use the referencedstructas the source for the fields allowed to:qquery parametersortquery parameterAdvisoryQueryandVulnerabilityQueryare two examples of how to use such a macro from now on.The actual descriptions format might need further changes based on the LLM/MCP effectiveness.
@ctron in the first review I would like to understand if the overall structure for the macro is fine and eventually apply refactoring to move it somewhere else in the project or rename them. Thank you.
Summary by Sourcery
Implement a custom derive macro to generate OpenAPI descriptions for
qandsortquery parameters based on struct fields, replace static documentation in the YAML spec, and integrate the newTrustifyQuerywrapper in advisory and vulnerability endpoints.New Features:
query-deriveproc-macro to automatically deriveQuerytrait implementations for custom query descriptionsquerycrate withTrustifyQuerywrapper andQuerytrait to generateqandsortparameter docs based on struct fieldsEnhancements:
QueryderiveTrustifyQuery<T>and deriveQueryon local query parameter structsBuild:
queryandquery-derivecrates to the workspace and update Cargo.toml configurations