Swagger documentation: Swashbuckle (hide methods/properties)

Question

I am using Swagger Swashbuckle to generate documentation. There are some methods in my controller and some properties in my models that I don't want to document. Is there any arrtibute or the property to leave or ignore specific methods from documentation?

Answer 1

For the method, you have couple of option:

1. Use Obsolete attribute. Then, you have to set the action - c.IgnoreObsoleteActions(); within the swagger configuration

2. Create a custom attribute and a swagger document filter. The document filter should iterate through each method and remove the method documentation if the method is having the custom attribute

For the properties, you can use JsonIgnoreAttribute

Answer 2

In addition to c.IgnoreObsoleteActions(), there is also c.IgnoreObsoleteProperties(), which hides the property from the documentation.

JsonIgnoreAttribute will stop the property deserializing when being received as part of a POST request body, which may not be what you want if you only wish to change the documentation and not the functionality.

Answer 3

In more recent version of Swashbuckle (Core2/3) XmlIgnore/JsonIgnore don't seem to work for properties.
Alternatively you can change the property access modifier to internal. This should prevent serialization and generated documentation.

I'm not sure about hiding whole controllers, you will probably need to add filters in your Swagger setup. I do have an example of hiding certain endpoints (for convenience I have prefixed routes for running locally):

        public void ConfigureServices(IServiceCollection services)
        {
            ...
            services.AddSwaggerGen(config => {
                config.SwaggerDoc("v1",
                    new OpenApiInfo {
                        Version = "v1",
                        Title = "Foo API",
                        Description = "Does foo things.",
                        Contact = new OpenApiContact {
                            Name = "nope",
                            Email = "[email protected]",
                        },
                    });
                // Include XML comments in Swagger docs
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                config.IncludeXmlComments(xmlPath);
                // Filter out prefixed routes
                config.DocInclusionPredicate(
                    (name, desc) => !desc.RelativePath.ToLower().StartsWith("MyDevPrefix"));
            });
    }

Answer 4

Just a note since I was also trying to figure out the JsonIgnore for properties not working...

The issue seems to be that newer versions of Swashbuckle for .Net Core do not support NewtonSoft out of the box.

• Install from NuGet

  Package Manager : Install-Package Swashbuckle.AspNetCore.Newtonsoft -Version 5.6.2
  CLI : dotnet add package --version 5.6.2 Swashbuckle.AspNetCore.Newtonsoft
  

• Add code to startup.cs

  services.AddSwaggerGen(c =>
  {
      c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
  });
  services.AddSwaggerGenNewtonsoftSupport(); // explicit opt-in - needs to be placed after AddSwaggerGen()
  

This worked for me, hope this helps someone else.