CODEWITHSUNDEEP
c#asp.net-web-apiswagger-uiswashbuckle
Ondrej Svejdar
Ondrej Svejdar

Reputation: 22064

Grouping of API methods in documentation - is there some custom attribute

I have controller like

public class UserController : ApiController
{
  [Route("api/user")]
  IHttpActionResult GetUser() { ... }
}

public class ResumeController : ApiController
{
  [Route("api/user/resumes")]
  IHttpActionResult GetResumes() { ... }
}

Which on swagger generates output like enter image description here

Is there a way (besides overriding default implementation by rolling out your own ISwaggerProvider or merging two controllers into one) to enforce the group name ? Something like

public class UserController : ApiController
{
  [Route("api/user")]
  [MagicalAttributeName(Group="User")]
  IHttpActionResult GetUser() { ... }
}

public class ResumeController : ApiController
{
  [Route("api/user/resumes")]
  [MagicalAttributeName(Group="User")]
  IHttpActionResult GetResumes() { ... }
}

Upvotes: 32

Views: 26040

Answers (4)

Ε Г И І И О
Ε Г И І И О

Reputation: 12351

If you happen to be developing an Azure Function App while useing OpenApi annotations from Microsoft.Azure.WebJobs.Extensions.OpenApi, the magic attribute is the 2nd (tags) parameter in OpenApiOperation.

public class ResumeFunction
{
  [FunctionName("GetUser")]
  [OpenApiOperation(operationId: "GetUser", "User")]
  public async Task<IActionResult> Run() { ... }
}

Upvotes: 0

np_np
np_np

Reputation: 31

I know it is very late but leaving the answer thinking it would be useful. You can use the ApiExplorerSettings, this is your magic attribute.
Something like this...

public class UserController : ApiController
{
  [Route("api/user")]
  [ApiExplorerSettings(GroupName="User")]
  IHttpActionResult GetUser() { ... }
}

public class ResumeController : ApiController
{
  [Route("api/user/resumes")]
  [ApiExplorerSettings(GroupName="User")]
  IHttpActionResult GetResumes() { ... }
}

Upvotes: 2

Andriy Tolstoy
Andriy Tolstoy

Reputation: 6090

You could also use SwaggerOperationAttribute: 

public class UserController : ApiController
{
    [Route("api/user")]
    [SwaggerOperation(Tags = new[] { "User" })]
    IHttpActionResult GetUser() { ... }
}

public class ResumeController : ApiController
{
    [Route("api/user/resumes")]
    [SwaggerOperation(Tags = new[] { "User" })]
    IHttpActionResult GetResumes() { ... }
}

Upvotes: 35

Ondrej Svejdar
Ondrej Svejdar

Reputation: 22064

There is a way - although there is no magic attribute - you can change default rules of grouping in swagger startup configuration in order to introduce your very own custom attribute.

GlobalConfiguration.Configuration 
 .EnableSwagger(c => {
   c.GroupActionsBy(apiDesc => apiDesc
     .GetControllerAndActionAttributes<MethodGroupAttribute>().Any() ?
        apiDesc.GetControllerAndActionAttributes<MethodGroupAttribute()
        .First().GroupName :
        apiDesc.ActionDescriptor.ControllerDescriptor.ControllerName);
 });


/// <summary>
/// Forces method to be displayed within specified group, regardless of controller
/// </summary>
[AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
public class MethodGroupAttribute : Attribute
{
    /// <summary>
    /// Group name
    /// </summary>
    public string GroupName { get; private set; }

    /// <summary>
    /// ctor
    /// </summary>
    /// <param name="groupName"></param>
    public MethodGroupAttribute(string groupName)
    {
        if (string.IsNullOrEmpty(groupName))
        {
            throw new ArgumentNullException("groupName");
        }
        GroupName = groupName;
    }
}

Usage:

[Route("api/user")]
[MethodGroup("User")]
IHttpActionResult GetUser() { ... }

Upvotes: 14

Related Questions