If you're creating public API, there's no question, that Swagger is one of the best ways to create documentation for it. If you're using WebApi, swashbuckle is one of the most popular libraries to use for creating API description in Swagger 2.0 format.

Sometimes, you're trying to reuse same API for public/internal use and some of the fields are not important to public consumers, so it would be better not to show them (don't forget though, that security through obscurity is not a way to secure stuff, so even if you hide them in documentation, make sure about safe usage on backend).

Currently to do so, you have two ways:

1) Use Obsolete attribute, which is not the ideal way, because it means something different (and in our sonar configuration usage is a major issue)
2) Write own attribute and use it in SchemaFilter:

public class HideInDocumentationAttribute : Attribute
{         
}

 public class PropertyFilter : ISchemaFilter
{
    public void Apply(Schema schema, SchemaRegistry schemaRegistry, Type type)
    {
        var hiddenProperties = type.GetProperties(BindingFlags.Instance | BindingFlags.Public)
            .Where(x => x.GetCustomAttribute<HideInDocumentationAttribute>() != null)
            .Select(x => x.Name.ToLowerFirstLetter())
            .ToList();

        schema.properties = schema.properties
            .Where(x => !hiddenProperties.Contains(x.Key))
            .ToDictionary(x => x.Key, x => x.Value);          
    }
}   
c#  webapi