Inside Web APIs and Customizing Swagger with Brady Gaster

Play Inside Web APIs and Customizing Swagger with Brady Gaster

Description

In this episode Brady Gaster schools Scott on how to customize the "Swagger" descriptive metadata format for Web APIs. You'll be able to craft your Web APIs and how they present themselves to customers with some of these advanced techniques within ASP.NET Web API.

Tag:

Azure

Embed

Download

Download this episode

The Discussion

  • User profile image
    nibras

    Good info. Thanks. 

  • User profile image
    joaomorais

    Hi Scott and Brady,

    I like those live demo and comments. This one about Swagger is very informative on an issue that people might run into like me.

    On that specific topic, I have existing Web API 2.0 (.NET 4.5) project which I have updated with Swashbuckle (5.2.2) and ran into those conflicts. I reproduced the code about the "IncludeParameterNamesInOperationIdFilter" in your video (at 4min35s).
    However, it did not work in my case.

    I looked at Swashbuckle code in GitHub, in the main class responsible to generate the document "SwaggerGenerator", and I found out that:
    - The Generator group the endpoints per HTTP method and URL-without-the-query-params
    - If a group has more than one element (i.e. conflict), then it calls "ConflictingActionsResolver()"
      Else it creates the "Operation" object and applies the "OperationFilter(s)"
     
    So, yes, there is a mean to overwrite the "OperationId", but it looks like it is court-circuited by "ConflictingActionsResolver()" before we get any chance to get call.
    Also, in the documentation of Swashbuckle, it is mentionned that Operation Filter are "Post-modify Operation descriptions", which seems to concur with the source code.

    In the video, you did not show where and how your operation filter was setup and used in your "SwaggerConfig.cs".

     

    # Please, could you share those details?
    # Or, please, could you advise in case I am doing something wrong?

    Thank you & happy new year !

    Joao M.

  • User profile image
    joaomorais

    @joaomorais:

    Took me sometime, but I got it working in the end. I am almost sure if we were able to see those details in the video, I would not have made the mistake to comment out the following line in my SwaggerConfig.cs file:
    ...
      c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
    ...

    I commented it out when I watched your OperationFilter, assuming it would resolve the conflict, but it does not. In fact, the OperationFilter just help with renaming of the 'operationId' in the post-generation of the operation description so that in the final document (and to follow Swagger specification) the OperationId is unique.

    By uncommenting back the line which always selects the first API description in the group, the conflict does still exists, but the select first allows the code to pursue and allows the OperationFilter to be applied so that the OperarationId gets modify in the final Swagger doc.

    As always, the devil is in the details.

    Thank you
    Joao M.

Conversation locked

This conversation has been locked by the site admins. No new comments can be made.