Swashbuckle (Swagger) for exposing SCIM API documentation

[boris-meerovich-sp]

I've tried to add support for Swagger UI to expose API documentation with fancy UI.

I can see all end-point in the UI and event envoke part of the end-points.
But there are several issues:

• Since my custom controllers don't expose actual actions, I can't add XML comments to the methods (the UI documentation collects all data from the methods XML comments). My workaround is to implement my custom IDocumentFilter and manually patch all custom end-points metadata. It works but very ugly and hard to maintain.
  My suggestion is to make all actions in BaseController virtual and then I could just override the methods and add my XML comments. The code of the overridden method will be only calling the base class.

• The second problem is the metadata method parameters. I'm talking about JObject parameters. I'm still looking for an elegant way to describe the parameters by XML comments.

Please, advise

[simpleidserver]

1. We are going to update the BaseApiController and put virtual.

2. For the "HTTP POST Search" operation, I suggest to pass a DTO and add comments to all the properties for example : SearchRepresentationRequest / attribute | excludedAttributes etc ...

For the other operations like "Add", "Update" and "Patch", the content of the request depends SCIM Schema for example : the "GroupSchema" defines a "displayName" parameter.
For this second scenario, we will add a new ApiDescriptionProvider and enrich the definition of the parameters with the information coming from the SCIM Schema.

[boris-meerovich-sp]

Awesome!!!
Thanks for the so quick responses!!!

[simpleidserver]

The project "SimpleIdServer.Scim.Startup" has been updated in the branch "release/1.1.8" :

• The swagger documentation is now enriched with information coming from SCIM Schemas.
• Some JObject parameter have been replaced but not all of them.

Missing parameters : Patch and Bulk

A pre-release version will be published next week (monday).

[boris-meerovich-sp]

I switched to work with branch "release/1.1.8".
All overrides are really helped me!!! Thanks.
Several issues I encountered with:

• In Users get endpoint for example, how to display example value like in post? Currently, I got this:
  
• In SimpleIdServer.Scim.Swashbuckle\SCIMSchemaGenerator.cs, GenerateReferencedSchema() method, row 176
  schema.Properties.Remove(schema.Properties.First(_ => .Key == "Attributes"));
  I got exception: System.InvalidOperationException: 'Sequence contains no matching element'
  for schema.Properties.First( => _.Key == "Attributes") row.
  Any of my schemas contain Attributes in Properties.
  Am I missing something?
• In the example value of my end-point there are some date-time values and here is how it looks like:
  
  The problem is "Unknown Type: date-time",
  Thanks

[simpleidserver]

• I don't think it's possible to set examples on HTTP GET operations, but only on HTTP POST, PATCH or PUT.
• The two issues are fixed in the latest commit : DateTime + Remove "Attributes" property.

[simpleidserver]

Do-you have any remarks on the Swagger endpoint / UI ?

If no, we will publish a new release.

[boris-meerovich-sp]

So far, so good!