[Feature Request] Overriding individual Property & Parameter types with [JsonSchema] Attribute

In some cases specific properties need to have their Schema type overriden. I would have thought that SwaggerGen would accept the use of the [JsonSchema] attribute from NJsonSchema, but it doesn’t seem to affect the generated schema.

Example 1:

    public class TagResponse
    {
        [JsonSchema(JsonObjectType.String)]
        [JsonConverter(typeof(HashIdsConverter))]
        public int? Id { get; set; }
        public string Name { get; set; }
    }

Here the int Id is converted to and from a string in the form of a HashId (ie. Id 5 == gR8q5b). I have specified that the JsonSchema of the type, yet it still comes out as an int in the Swagger models.

Example 2:

        [HttpGet(TagRoutes.Get, Name = "GetTag")]
        [HashIdFilter(TagRoutes.IdParam)]
        public ActionResult<TagResponse> Get([JsonSchema(JsonObjectType.String)] int tagId)
        {
              //Do stuff
        }

Here the id parameter is an int and I have this action annotated with a filter. This filter transparently converts the int id to and from the string HashId. Requests are expected to provide a string Id, and responses respond with a string Id. However, the Swagger UI shows this as requiring an int which removes the ability to test this endpoint through Swagger as strings are not accepted to execute a request…

---

Can this library support the use of the [JsonSchema] attribute to override the schema types of individual properties and parameters?

[domaindrivendev]

Sorry, I misinterpreted your original post.

Swashbuckle does have an “add-on” package (described here) for overriding the generated Swagger with attributes. That package doesn’t currently support your use case but could be updated to do so relatively easily if you’re interested in contributing?

With that said, an attribute-based approach puts the burden of aligning documentation with actual behavior on the API developer, and this deviates somewhat from the projects original goals. Instead I would encourage the use of “Swagger filters” (described here) to hook into the Swagger generation process and automatically honor the custom serialization behaviors you’ve implemented in HashIdsConverter and HashIdFilter.

For example, you could wire up the following Schema Filter to automatically detect properties decorated with your custom converter and override the schema accordingly.

// HashIdsSchemaFilter.cs
public class HashIdsSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        var jsonObjectContract = context.JsonContract as JsonObjectContract;
        if (jsonObjectContract == null) return;

        foreach (var propertyName in schema.Properties.Keys)
        {
            var propertySchema = schema.Properties[propertyName];

            // Get the underying PropertyInfo
            var jsonProperty = jsonObjectContract.Properties[propertyName];
            var propertyInfo = jsonProperty.DeclaringType.GetProperty(jsonProperty.UnderlyingName);

            // Check if it's decorated with the specific converter
            var jsonConverterAttribute = propertyInfo.GetCustomAttributes(true)
                .OfType<JsonConverterAttribute>()
                .FirstOrDefault();

            if (jsonConverterAttribute != null && jsonConverterAttribute.ConverterType == typeof(HashIdsConverter))
            {
                propertySchema.Type = "string";
                propertySchema.Format = null;
            }
        }
    }
}

// Startup.cs
c.AddSwaggerGen(c =>
{
    ...
    c.SchemaFilter<HashIdsSchemaFilter>();
});

For the second scenario (i.e. where you’ve customized the parameter serialization behavior with HashIdFilter), you would do something similar but with an Operation Filter instead.

[wizofaus]

BTW, I figured it out how to add that functionality by picking up the ‘cref’ parameter from xml comments, just need to add this to the end of XmlCommentsParameterFilter.ApplyParamTags:

                var cref = paramNode.GetAttribute("cref", "")?.Split(':').Last();
                if (!string.IsNullOrEmpty(cref) && System.Type.GetType(cref) is System.Type type)
                {
                    parameter.Schema = context.SchemaGenerator.GenerateSchema(type, context.SchemaRepository);
                }

Obviously could use some error handling etc., but the basic principle works. I’m not quite sure why the xml file has “T:” pre-pended to whatever type name you put in the cref attribute currently, hence the Split(':').Last().