asp.net-web-api - mvc - web api query string parameters

Restricción del contenido de la Página de ayuda automática cuando se utiliza el Enrutamiento de atributos en la API web 2

Question

Actualmente estoy implementando una API web usando el enrutamiento de atributos de la API web 2 ( http://www.asp.net/web-api/overview/web-api-routing-and-actions/attribute-routing-in-web-api -2 ). También estoy usando el módulo Páginas de Ayuda para generar automáticamente documentación a partir de comentarios XML ( http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages ).

Para esta API, proporciono soporte para extensiones opcionales de formato de retorno, de modo que cada método API tenga un par de rutas definidas así:

[HttpGet]
[Route("Path/Foo")]
[Route("Path/Foo.{ext}")]
public HttpResponseMessage DoFoo()
{
    // Some API function.
}

Esto le permite al usuario golpear cualquiera de estos y obtener un resultado:

www.example.com/api/Controller/Path/Foo 
www.example.com/api/Controller/Path/Foo.json
www.example.com/api/Controller/Path/Foo.xml

Mi problema es que cuando las páginas de ayuda usan MapHttpAttributeRoutes () para generar documentación, está recogiendo ambas rutas para cada método. Así que ahora veo ayuda para:

api/Controller/Foo
api/Controller/Foo.{ext}

Pero solo quiero ver:

api/Controller/Foo.{ext}

Preferiría ocultar la ruta de no extensión en cada método, de modo que cada método solo muestre una sola entrada de la página de Ayuda.

¿Alguien más ha intentado algo similar? ¿Hay algún trabajo que me falta?

Answer 1

Mi pregunta sería, ¿los consumidores de su API sabrán fácilmente que el {ext} es opcional? ... Personalmente, preferiría el comportamiento predeterminado ... pero de todos modos los siguientes son algunas soluciones que puedo pensar:

1. Una solución rápida y sucia. Divida el DoFoo en 2 acciones como DoFoo () y DoFooWithExt tal vez. Tenga en cuenta que estoy usando un atributo llamado ApiExplorerSettings , que es para propósitos de la página de ayuda. Ejemplo a continuación:

   [HttpGet]
   [Route("Path/Foo")]
   [ApiExplorerSettings(IgnoreApi=true)]
   public HttpResponseMessage DoFoo()
   {
       return DoFooHelper();
   }
   
   [HttpGet]
   [Route("Path/Foo.{ext}")]
   public HttpResponseMessage DoFooWithExt()
   {
       return DoFooHelper();
   }
   
   private HttpResponseMessage DoFooHelper()
   {
       //do something
   }

2. Cree un ApiExplorer personalizado (que la característica de la página de ayuda usa internamente) y verifique las rutas específicas como las siguientes y puede decidir si mostrar la acción o no para esa ruta en particular.

   // update the config with this custom implementation
   config.Services.Replace(typeof(IApiExplorer), new CustomApiExplorer(config));
   
   public class CustomApiExplorer : ApiExplorer
   {
       public CustomApiExplorer(HttpConfiguration config) : base(config)
       {
   
       }
   
       public override bool ShouldExploreAction(string actionVariableValue, HttpActionDescriptor actionDescriptor, IHttpRoute route)
       {
           if (route.RouteTemplate.EndsWith("Path/Foo", StringComparison.OrdinalIgnoreCase))
           {
               return false;
           }
   
           return base.ShouldExploreAction(actionVariableValue, actionDescriptor, route);
       }
   }

3. Obtenga una lista de todas las ApiDescription del ApiDescription predeterminado y luego filtre las descripciones que no le ApiExplorer . Ejemplo: Configuration.Services.GetApiExplorer().ApiDescriptions.Where((apiDesc) => !apiDesc.RelativePath.EndsWith("Path/Foo", StringComparison.OrdinalIgnoreCase))