swagger-api / swagger-api/swagger-core

Propagate JsonView annotation when resolving schema properties

Open
#4,719 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

backlog
Dominant language
Java
Stars
7.5k
Forks
2.3k
Avg merge
18h 1m
Merged PRs (30d)
10

Description

I'm currently using Jackson's @JsonView annotation to include/exclude class properties based on the API operation that is being performed (e.g., create, update, read, etc.).

I have a specific need where I must annotate a class with @SchemaProperties, @SchemaProperty, and @Schema. However, the ModelResolver (Jackson-specific implementation of ModelConverter) ends up not propagating the @JsonView annotation when resolving the classes of the properties defined with @SchemaProperties. This causes the resulting schema to include properties that should be excluded for certain operations.

https://github.com/swagger-api/swagger-core/blob/e6d3fa3608d32d7c74fd62a007253f440a1f773d/modules/swagger-core/src/main/java/io/swagger/v3/core/jackson/ModelResolver.java#L881

https://github.com/swagger-api/swagger-core/blob/e6d3fa3608d32d7c74fd62a007253f440a1f773d/modules/swagger-core/src/main/java/io/swagger/v3/core/jackson/ModelResolver.java#L1775

Example

public class CommonViews {

    public static class Update { }

}

@PatchMapping("/update")
public void update(@JsonView(CommonViews.Update.class) AnnotatedWithSchemaProperties payload) {
    // logic
}

@SchemaProperties({
    @SchemaProperty(
        name = "my_custom_property",
        schema = @Schema(implementation = PropertyAnnotatedWithJsonView.class)
   )
})
public class AnnotatedWithSchemaProperties {
}

public class PropertyAnnotatedWithJsonView {

  private String alwaysIncludedProp;

  @JsonView(CommonViews.Update.class)
  private String includedOnlyWhenUpdating;

}

Alternative Solution

I was able to overcome the problem for now by defining a "dummy" setter method, causing the schema to be generated the way I'd expected:

@JsonProperty("my_custom_property")
public void setMyCustomProperty(PropertyAnnotatedWithJsonView myCustomProperty) {
    // logic
}

Additional Context

  • I'm using Swagger Core via Springdoc (which can be assumed based on the example above)
  • In case it is helpful, I'm using @SchemaProperties/@SchemaProperty/@Schema in a class that allows dynamic properties to be provided by consumers via the @JsonAnySetter/@JsonAnyGetter annotations. @SchemaProperties/... allow me to provide some examples in the generated schema to our consumers.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in modules/swagger-core/src/main/java/io/swagger/v3/core/jackson/ModelResolver.java at the referenced lines around 881 and 1775, tracing how @SchemaProperties and @SchemaProperty implementations are resolved. Add coverage for the supplied @JsonView and @SchemaProperties example, then verify that properties excluded for the active view are absent from the generated schema.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, backend-api-design
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.