How to filter and customise which API endpoints are exposed

[rockgecko-development]

I needed a way to customise which API endpoints are exposed, so I created a custom DocumentHelper and overrode List<MethodInfo> GetHttpTriggerMethods(Assembly assembly), providing my own custom implementation. I also needed to add a custom OpenApiHttpTriggerContext. This works great for me on v0.5.1 - here's a gist if anyone would like to see how: https://gist.github.com/rockgecko-development/02b53d05eab230e3989fce2c2ab5ba80

I see that following the out-of-process refactoring in #142 , this method has been removed from IDocumentHelper interface and put into an extension function. How can I override this now, without also reimplementing all of Document as well?

[justinyoo]

Related to #175

@rockgecko-development We got reported not all the list of the latest version of 0.8.0-preview packages have been released. We're in the middle of investigating it and will be fixed soon. In the meantime, please stick on 0.7.2-preview.

[rockgecko-development]

Sorry I can't update to 0.7.2, I'm still on 0.5.1 due to #122

I jumped to github to get the source code to figure out how to override what I needed to, and that's when I noticed it had been removed from IDocumentHelper.
Not using the latest, just flagging this as a possible API design issue.

[xsneebsx]

Hello,

I've come across a similar issue here where I'd like to customise the the way the open api parameters are discovered since the code i have doesn't need to use the attributes and can pull the paramter details directly from the method parameters. This is done using custom bindings similar to the ones available in AspNet (ie. FromBody, FromQuery, etc).

I had a look through and noticed that dependency injection is used in both the in process and out of process worker, would it be possible to have an interface that gets injected into the trigger contexts to allow customisation by adding a custom implementation of an interface to the DI layer?

Overview of changes i think would need to be done to make this work:

• Allow injecting this (new?) document helper interface in the constructors of the trigger contexts
• Move the DocumentHelperExtensions to this interface so it can be used as the default behaviour
• Consideration still needs to be done in terms of how the injection is done so the default behaviour could be used alongside additional implementations

I did some searching and wasn't able to find anything around what plans there are for allowing this customisation outside of this issue, but if there is something around let me know and I'll have a look at it.

[justinyoo]

@xsneebsx Let's discuss. But I'm considering:

• A querystring parameter like ?filter=admin should be used so that the OpenAPI endpoints should recognise it. eg) http://localhost:7071/api/swagger/ui, http://localhost:7071/api/swagger/ui?filter=admin, or http://localhost:7071/api/swagger/ui?filter=consumer.
• The querystring parameter should be handled by the OpenApiOperationAttribute class.

NOTE: filter is just an arbitrary name.

[xsneebsx]

Ah yes, i think i misunderstood the filtering by tags requirement and making it a supported query parameter on the openapi endpoints makes more sense. I can add a query parameter of tagsFilter that could work or an alternative might be to support multiple openapi documents which is supported in the swaggerui.

The swaggerui config object has a urls property which is an array of { url: string, name: string } which enables the drop down list at the top in the swagger ui that lets you switch the displayed openapi document. This would require some additional support since there would need to be a way to define which api operations are part of a given openapi document. The way that swashbuckle supports this is by using the

• Additional string replacement performed in the index.html to add multiple urls to the swaggerui config object if there is more than 1 document
• Additonal configuration to allow including api operations within a document
• Changes to the openapi routes to support extracting the openapi document that is being requested
• Allow specifying a default document

Reference

• Swashbuckle uses the aspnet controller attribute [ApiExplorerSettings(GroupName = "MyGroupName")] to support this, not sure if there's an out of the box attribute or we could define one
• The urls property definition link is https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/ and is listed under first table calledCore
• Config object json example with urls property

var configObject = {
	...
	"urls":[{
		"url":"/swagger/v1/swagger.json",
		"name":"My API V1"
	},{
		"url":"/swagger/v2/swagger.json",
		"name":"My API V2"
	}]
	...
}

[justinyoo]

@xsneebsx It seems that we need to split issues identified here into several ones. This issue is all about the filtering endpoints to be exposed. All others might be relevant but don't seem to be necessary at once.

[xsneebsx]

No worries, I didn't mean to cover multiple issues in this one. I've split out my issue to #220 which is specifically around how to define parameters without needing the attributes and have updated my PR to mention the other issue as well.