Swashbuckle EF Core hide properties for post/put documentation

Question

Summary

I would like to hide properties from the generated documentation model for PUT/POST requests.

More Detail

I would like to create a nicely documented API for a system I'm working on. I would like to use Swashbuckle/Swagger to automatically generate the documentation. I am using Entity Framework to define the relationship between objects in the system.

Here is an example relationship between objects.

User.cs

public class User
{
    public int Id { get; set; }
    public string ExternalReference { get; set; }
    public string Name { get; set; }

    public ICollection<Post> Posts { get; }
}

Post.cs

public class Post
{
    public int Id { get; set; }
    public string ExternalReference { get; set; }
    public string Content { get; set; }
    public int UserId { get; set; }

    public User User { get; set; }

}

The following example value is generated for my GET /api/posts/{id} endpoint.

GET /api/posts/{id}

{
  "id": 0,
  "externalReference": "string",
  "content": "string",
  "userId": 0,
  "user": {
    "id": 0,
    "externalReference": "string",
    "name": "string",
    "posts": [
      null
    ]
  }
}

This is what I would like to see, it's relevant to potentially return the User object as well.

The following is the example value generated for my POST /api/posts endpoint

POST /api/posts

{
  "id": 0,
  "externalReference": "string",
  "content": "string",
  "userId": 0,
  "user": {
    "id": 0,
    "externalReference": "string",
    "name": "string"
  }
}

In my mind at least I feel the user section of the example isn't relevant for POST or PUT only the userId property is. The generated example value isn't too bad in this simple example, but if I start having objects with multiple relationships I feel it can get messy.

The question again

Is there an elegant way of supressing relational objects from the generated swagger documentation ONLY for PUT/POST methods?

In my opinion the solution is to not expose your database entities as API DTOs. Instead specify the API DTOs and map data from database entities to/from the DTOs. Tools like AutoMapper or Mapster can help you do these mappings if they are very trivial. — juunas
Even if you hide it from the documentation, the user can still specify them and they will be bound if you take that DB model as a parameter. — juunas
@juunas Thank you, so in effect create DTO objects for every item I would like to expose via the API? Would I have to create separate DTO objects for both POST and GET methods to fix the concerns I had in my original question? — CT14.IT
Swashbuckle allows you to create your own examples for requests and responses. — DalSoft
We usually have a separate DTO for the read and write endpoints so only the fields relevant to the request are in the model. Often the read model has more data in it. — juunas

Rena Rena · Accepted Answer · 2020-10-14T08:59:31

You could custom a OperationFilter like below:

public class CustomOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if (operation.OperationId == "Posts_post" || operation.OperationId == "Posts_put")
        {
            operation.RequestBody = new OpenApiRequestBody()
            {
                Content = new Dictionary<string, OpenApiMediaType> {
                {"application/json",
                    new OpenApiMediaType()
                    {

                        Schema = new OpenApiSchema(){
                            Example = new OpenApiObject
                                {
                                    ["ID"] = new OpenApiInteger(0),
                                    ["UserId"] = new OpenApiInteger(0),
                                    ["ExternalReference"] = new OpenApiString("string"),
                                    ["Content"] = new OpenApiString("string")
                                }
                        }
                    }
                }
            }
            };
        }
        else
        {
            return;
        }
       
    }
}

Add the name on HttpVerb attribute:

[HttpPut("{id}",Name = "Posts_put")]
public async Task<IActionResult> PutPost(int id, Post post)
{....}

[HttpPost(Name ="Posts_post")]
public async Task<ActionResult<Post>> PostPost(Post post)
{...}

Startup.cs:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
        c.OperationFilter<CustomOperationFilter>();   //add this...
    });
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Result:

Swashbuckle EF Core hide properties for post/put documentation

1 Answers