Skip to main content

SwashBuckle - Swagger Open API Documentation


Swashbuckle Open API


Swagger is Open API documentation used to understand the various methods and the request/responses of various endpoints. It generates the Web API SDK for clients.


Swashbuckle.AspNetCore is an open-source project for generating Swagger documents for ASP.Net Core Web APIs. Another open-source project is NSwag for generating swagger documents.


Enable Swagger in .NET Core Apps - 

Note - Install the Swashbuckle.AspNetCore NuGet package into your solution.Don't install Swashbuckle.AspNetCore.Swagger package)


Add the below to the Configure() Method - 

app.UseSwagger();

app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "AppName"); });


using Swashbuckle.AspNetCore.Examples;
using Swashbuckle.AspNetCore.Swagger;

public void ConfigureServices(IServiceCollection services)
{
    // Register the Swagger generator, defining 1 or more Swagger documents
    services.AddSwaggerGen(c =>
    {
        var appVersion = "v" + typeof(RuntimeEnvironment).GetTypeInfo().Assembly.GetCustomAttribute<AssemblyFileVersionAttribute>().Version;
        c.SwaggerDoc("v1", new Info 
        { 
            Title = "My API",
            Description = "API Description"
            Contact = new Contact
            {
                Name = "Team Name",
                Url = "Link to team confluence/documentation pages"
            } 
            Version = appVersion 
        });

        c.AddSecurityDefinition("Bearer", new ApiKeyScheme
        {
            In = "header",
            Description = "Please Enter OAuth with Bearer into field",
            Name = "Authorization",
            Type = "apiKey"
        });

        c.AddSecurityRequirement(new Dictionary<string, IEnumerable<string>> {{ 'Bearer', Enumerable.Empty<string>()}});

        c.CustomSchemaIds((type) => type.ToString()
             .Replace("[", "_")
             .Replace("]", "_")
             .Replace("{", "_")
             .Replace("}", "_")
             .Replace(",", "_")
             .Replace("`", "_")
        );

        c.OperationFilter<SwaggerHeadFilter> //Research
        c.Operation<ExamplesOperationFilter>();

        //Set the comments path for the Swagger JSON and UI - Xml files containing the summary comments are created in the ./bin folder of the basedirectory
        //Swagger uses that to for showing the summary
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
        c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFile2));
    });
}

//Controller
[ProducesResponseType(typeof(Task<ResponseType>), 200)] //POST
[ProducesResponseType(typeof(Task<OkResult>), 200)]          //DELETE
[ProducesResponseType(typeof(Task<ResponseType>), 201)] //POST(Create)
[ProducesResponseType(typeof(Task<ResponseType>), 400)]
[ProducesResponseType(typeof(Task<ResponseType>), 401)]
[ProducesResponseType(typeof(Task<ResponseType>), 404)]
[ProducesResponseType(typeof(Task<ResponseType>), 416)]
[ProducesResponseType(typeof(Task<ResponseType>), 500)]
[SwaggerRequestExample(typeof(Request), typeof(RequestExampleClassType))]
[HttpPost("Route")]
[HttpGet("Route")]
[HttpDelete("Route")]

//Examples Class
public class RequestExample : IExamplesProvider
{
    public object GetExamples()
    {
        return new Request
        {
            {field} = value,
            ....
        }
    }
}


Comments

Popular posts from this blog

How to clear Visual Studio Cache

How to clear visual studio cache Many times, during development you would face situations where project references are not loaded properly or you get missing/error DLL's. This is because the Component cache gets corrupted randomly and without any warnings. The first option that needs to be done is to clear component cache and restart Visual Studio since the Cache might be holding onto previous DLL versions. Here are the steps on how to clear Visual Studio Cache, Clearing Component Cache: Close all Visual Studio Instances running in your machine. Also, make sure devenv.exe is not running in the Task Manager Delete the Component cache directory - %USERPROFILE%\AppData\Local\Microsoft\VisualStudio\1x.0\ComponentModelCache Restart Visual Studio The above steps should fix the cache issue most of the times, but some times that is not enough and you need to perform the below steps as well. Clearing User's Temp Folder: Open the temp folder in this locatio n -  %USERPROFILE%\AppData\Loc

How to dependency inject to static class

.Net core supports dependency injection. There are many ways that you can inject services like constructor injection, action method injection, property injection. But there will be scenarios where you need to inject dependency services to static classes. For example, injecting services to extension methods. First, create a static class with a one property IServiceProvider type public void ConfigureServices(IServiceCollection services) { services.AddScoped<ILoggerEntry, LoggerEntry>(); services.AddTransient<IMongoRepository, MongoRepository>(); } Second, configure your services in ConfigureServices() method in Startup.cs and define the lifetime of the service instance using either Transient, Scoped or Singleton types. public void ConfigureServices(IServiceCollection services) { services.AddScoped<ILoggerEntry, LoggerEntry>(); services.AddTransient<IMongoRepository, MongoRepository>(); } For the next step to configure the Static class provider proper

PCF Health Check Delay - Invocation timeout

In PCF we can set up the health check invocation timeout to execute X seconds after the instance has been created.  But before that, let's understand the PCF Health Check Lifecycle. Stage 1: The application is deployed to PCF Stage 2: When deploying the app, a health check type is specified and optionally a timeout. If a health check type is not specified, then the monitoring process defaults to a port health check Stage 3: Cloud Controller stages, starts, and runs the application Stage 4: Based on the type specified for the app, Cloud Controller configures a health check    that runs periodically for each app instance Stage 5: When Diego starts an app instance, the app health check runs every two seconds until a response indicates that the app instance is healthy or until the health check timeout elapses. The 2-seconds health check interval is not configurable Stage 6: When an app instance becomes healthy, its route is advertised, if applicable.                  Subsequent hea