ApiDescription.ResponseDescription is not initialized

[Tasteful]

When creating an ApiDescription from it's own ctor the ResponseDescription is not initiated and the set-property is internal.

AspNetWebStack/src/System.Web.Http/Description/ApiDescription.cs

Line 85 in 62d0b2d

public ResponseDescription ResponseDescription { get; internal set; }

Workaround

var apiDescriptor = new ApiDescriptor();
typeof(ApiDescription).GetProperty(nameof(ApiDescription.ResponseDescription)).SetValue(apiDescriptor, new ResponseDescription());

[dougbu]

Thank you for your feature request. To help us prioritize this feature correctly, could you please provide as much information as possible about the scenarios and their importance?

[Tasteful]

In our project we are creating the ApiDescription dynamic depend on the entities. Now when the set-method for the ResponseDescription property is internal it exists no way (except from using reflection) to set the ResponseDescription object that contains the ResponseType information that will be used when creating the api documentation.

[dougbu]

@Tasteful where are you attempting to change the ApiDescription.ResponseDescription? That property should not be null in most cases. And, since ResponseDescription properties are all publicly settable, your application should be able to change everything.

[Tasteful]

In our case we are implementing an own IApiExplorer that inherits the default ApiExplorer. Whe the ApiDescriptors are returned we find an generic controller, lets call that 'GenericController' that have a route template like '/api/{entityType}'. For each domain entity that can be used with our CRUD operations we will make a copy of the ApiDiscription for the GenericController, replace the entityType-placeholder in the routeTemplate and set the correct ReturnType.

This will allow us to have one generic controller for basic CRUD operations but create an Api documentation that contains all the different methods that are typed; instead of a generic method that are untyped and the user need to lookup in some docs site the possibilities of different entity types. In the end we get a nice swagger specification out that are typed.

[dougbu]

🆗 thanks for the information about your scenario.

The exact issue is however still not clear to me. Have you encountered a case in which ApiDescription.ResponseDescription is null? Or, do you prefer to overwrite that property instead of ResponseDescription's three properties?

[Tasteful]

If I rcreate a new ApiDescription() the ResponseDescription-property is null.

The other properties that not have a public setter is initiated in the ctor

• SupportedRequestBodyFormatters
• SupportedResponseFormatters
• ParameterDescriptions

but the ResponseDescription has an internal set-method and is not initiated in the ctor.

The ResponseDescription property is always set if usage is from the the standard ApiExplorer that finding all controllers and create ApiDescription for all the action methods are using the internal set method to populate the ResponseDescription with an instance.

Solutions to make less confusions for developers:

• the property set-method should be public.
• the property should be initiated in the ctor.
• the ApiDescription-class should be sealed and have an internal ctor so it is clear for developers that it is no reason for them to try to create and use a new instance of this class.

[Tasteful]

I have the GenericController, and the EntityA, and EntityB. From the ApiDescription that default ApiExploreris creating I append two new ApiDescriptors that is a clone of the ApiDescriptor. Each clone of the ApiDescriptor have replaced input and outyp types so the api documentation looks fully typed even if the execution using the same GenericController.

[dougbu]

the ApiDescription-class should be sealed and have an internal ctor so it is clear for developers that it is no reason for them to try to create and use a new instance of this class.

We couldn't do this for back-compatibility reasons. But, I'm curious: What approach would you use to add ApiDescriptions if we went this route? E.g. would you extend your Reflection workaround to construct the descriptions?

[Tasteful]

If ApiDescription have an internal ctor and was sealed then I have think the design with having the IApiExplorer and not only a public sealed class ApiExplorer (but can be used on the same way in DI if they are registrated correctly) becaues it exists no reason to have an interface for the IApiExplorer if it not was possible to make an own implementation. (And yes you can create an own implementation of the IApiExplorer but you will not be able to create any ApiDescriptions so creating an own implementation is meaningless.)

[Tasteful]

Also updated the PR to set the property in the ctor instead of making it public. This change will make the implementation binary compatible with the existing one. If changing the property from internal to public it can break any reflection usage.

[dougbu]

Will get #146 into the next milestone.