Expose properties of resource

[bjornharrtell]

Needed for external inspection to for example generate schema.

Can solve part of #140.

[joukevandermaas]

I'm not entirely sure why this would help with #140, since I've never used Swashbuckle before. I'm generally pretty hesitant to making things public, but I'm assuming you have a specific use in mind for this API.

Can you maybe explain with a code snippet or whatever?

[bjornharrtell]

I don't have a good code snippet to show but I hope I can explain the purpose better without requiring previous knowledge. So Swashbuckle works by introspecting the Web API controllers, to generate a swagger document which essentially is a schema/documentation of the REST API. The built in introspection in Swashbuckle will only see the type as returned by an ApiController, even if it is transformed by Saule the corresponding ApiResource, because it does not understand or consider the ReturnsResourceAttribute from Saule.

However, I can provide code to customize the introspection. In that code I can find the actual ReturnsResourceAttribute instance for the controller and then proceed to customize the schema to represent a JSON API resource instead of the plain JSON representation of a model. To be able to implement the actual customized schema I need to be able to look at the defined Attributes, ResourcesRelationships and IdProperty on the ApiResource which is why I want them exposed.

For now I only have a hacked solution for the actual customization logic but I think that I will eventually be able to provide an extension to Swashbuckle that can easily be used in any Saule project. This would be similar to https://github.com/rbeauchamp/Swashbuckle.OData which provides something similar but for OData.

[joukevandermaas]

Ok, that sounds good. I'll merge this if you can rebase on master. Thanks for the explanation!

[bjornharrtell]

Rebased. I've also added a property OriginalName to ResourceAttribute as that too is useful the context of introspection for Swashbuckle, I hope that's acceptable.

[joukevandermaas]

Since people can pass any string to this constructor (through Attribute in ApiResource), I wonder if we should still normalize it, but to PascalCase (conventional for C# properties). That way Swashbuckle can get the property name (assuming that is the intention) and people can still specify the attributes in JSON API form if they want.

Of course if we do that, it should be called something like PropertyName, not OriginalName. Relationships (ResourceRelationship) should probably also get this property, just to be consistent.

Does this make sense to you? Am I correctly understanding the purpose of this new property?

[bjornharrtell]

Yes I think it would make sense, but it would also break existing public API?

[bjornharrtell]

Ah no, I misread you and now it makes even more sense. I'll try to make the changes as suggested.

[bjornharrtell]

@joukevandermaas I hope this is good to go now.

[joukevandermaas]

Yup! thanks for seeing this through!