Swashbuckle.webapi: OAuth endpoint documentation

[Misiu]

I find Swashbuckle very helpful, in just couple of minutes I got it working in my solution.
Everything works great except one thing - I'm securing my API using JWT token using technique from this blog: http://bitoftech.net/2014/10/27/json-web-token-asp-net-web-api-2-jwt-owin-authorization-server/
Swashbuckle is generating documentation for all Controllers, but I don't know how to add documentation to "virtual" controller that is responsible for token generation.

I have code similar to this:

c# OAuthAuthorizationServerOptions OAuthServerOptions = new OAuthAuthorizationServerOptions() { AllowInsecureHttp = true, TokenEndpointPath = new PathString("/oauth2/token"), AccessTokenExpireTimeSpan = TimeSpan.FromMinutes(30), Provider = new CustomOAuthProvider(), AccessTokenFormat = new CustomJwtFormat("http://jwtauthzsrv.azurewebsites.net") };

To generate token user must go to _TokenEndpointPath_, send username, password, grant_type and client_id to get token that can be then passed with other api requests.

Can I add information about that oauth endpoint to Swagger?

[domaindrivendev]

The easiest way to do this right now is with a simple Document Filter (see readme) that manually adds a definition for the additional operation:

public class TokenEndpointDocumentFilter : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
    {
        swaggerDoc.paths.Add("oauth2/token", new PathItem
        {
            post = new Operation
            {
                tags = new string[] { "Authentication" },
                summary = "Authenticates provided credentials and returns an access token",
                operationId = "OAuth2TokenPost",
                consumes = new string[] { "application/x-www-form-url-encoded" },
                produces = new string[] { "application/json" },
                parameters = new List<Parameter>
                {
                    new Parameter
                    {
                        name = "username",
                        @in = "formData",
                        type = "string"
                    },
                    new Parameter
                    {
                        name = "password",
                        @in = "formData",
                        type = "string"
                    },
                    new Parameter
                    {
                        name = "grant_type",
                        @in = "formData",
                        type = "string"
                    },
                    new Parameter
                    {
                        name = "client_id",
                        @in = "formData",
                        type = "string"
                    }
                },
                responses = new Dictionary<string, Response>
                {
                    {
                        "200",
                        new Response
                        {
                            description = "Success",
                            schema = new Schema
                            {
                                type = "object",
                                properties = new Dictionary<string, Schema>
                                {
                                    {
                                        "access_token",
                                        new Schema
                                        {
                                            type = "string"
                                        }
                                    },
                                    ... etc. ...
                                }
                            }
                        }
                    }
                }
            }
        });
    }
}

It's also worth noting that the swagger-spec also includes a section specifically for describing the various security schemes (including the various oauth flows) that are applicable to your API. You can read more about that here - http://swagger.io/specification/#securitySchemeObject.

However, the tooling is typically behind the spec and as of writing, the swagger-ui doesn't currently have built in support for the "password" flow. So, you can go ahead and add a definition for the above (see here for an example) to the generated swagger.json but the UI won't appear any differently. However, sounds like support for this is planned at some stage - https://github.com/swagger-api/swagger-ui/issues/807

[Misiu]

@domaindrivendev thank You for sharing this. I was looking for same functionality, wanted to create new issue but I found this one. Solution works great.

[ChrisSchmi]

@domaindrivendev Is there another way to add a second method to an endpoint with the same URL?
Your example shows adding stuff to swaggerDoc.paths, which is an IDictionary.
My problem is, that the OAuth2 Server in ASP.NET uses the same URL for getting the access token and getting a new one by "refresh token".

please see here:
https://stackoverflow.com/questions/52165981/how-to-add-multiple-actions-to-swashbuckle-document-path-pointing-to-one-endpoin