swagger-pbp-outline-notes.md

Intro - Finding APIs, no documentation, building APIs, test harnesesses etc Swagger - specification no referred or renamed to OpenAPI Spec. Restful interface to documetation of your APIs. Swashbuckle - OSS implementation for ASP.NET / Ahoy => ASP.NET Core on github

ASP.NET Docs page - https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger

We are going to use VS for Mac! Wait what?? (can have some discussion here)

Let's do this..

# using yeoman generator for full API template
yo aspnet 

# select Web API Application

superherogen

cd superherogen

# migrate the application to csproj/MSBUILD  version
dotnet migrate

• Open the project in Visual Studio for Mac
• Restore Nuget Packages - can use dotnet restore OR VS for Mac

Add the Swashbuckle Nuget Package

services.AddSwaggerGen();

app.UseSwagger();
app.UseSwaggerUI();

Browse to: http://localhost:<random_port>/swagger/ui Show json that drives the UI: http://localhost:<random_port>/swagger/v1/swagger.json

Custom Info

Show how to add the custom info header in the UI

snippets added for this

XML Comments

 //Determine base path for the application.
var basePath = PlatformServices.Default.Application.ApplicationBasePath;

//Set the comments path for the swagger json and ui.
var xmlPath = Path.Combine(basePath, "TodoApi.xml"); 
options.IncludeXmlComments(xmlPath);

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>

add remarks to xml comments

/// <remarks>
/// Note that the key is a GUID and not an integer.
///  
///     POST /Todo
///     {
///        "key": "0e7ad584-7788-4ab1-95a6-ca0a5b444cbb",
///        "name": "Item1",
///        "isComplete": true
///     }
/// 
/// </remarks>

Response codes

/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(typeof(TodoItem), 201)]
[ProducesResponseType(typeof(TodoItem), 400)]

THE HEROESCONTROLLER CLASS WE WILL CREATE

using Microsoft.AspNetCore.Mvc;
using GenFu;

/// <summary>
/// API endpoint for generating random Superhero or getting a Superhero name for a Persons name
/// </summary>
[Route("api/[controller]")]
[Produces("application/json")]
public class HeroesController : Controller
{
    /// <summary>
    /// Returns a Person object with the Superhero name generated
    /// </summary>
    /// <param name="firstName">First Name of the Person object</param>
    /// <param name="lastName">Last Name of the Person object</param>
    /// <returns>New Person object</returns>
    /// <response code="200"></response>
    [ProducesResponseTypeAttribute(typeof(Person), 200)]
    [HttpGet("{firstName}/{lastName}")]
    public Person Get(string firstName, string lastName)
    {
        var p = new Person() { FirstName = firstName, LastName = lastName };
        p.SetHeroName();

        return p;
    }

    /// <summary>
    /// Returns a random Person object using GenFu
    /// </summary>
    /// <remarks>
    /// GenFu is an Open Source library for creating contextual based test data
    /// is available at https://github.com/MisterJames/GenFu
    /// </remarks>
    /// <returns>New Person object</returns>
    /// <response code="200"></response>
    [HttpGet()]
    public Person Get()
    {
        var p = A.New<Person>();
        p.SetHeroName();

        return p;
    }
}

Custom index page template

https://github.com/domaindrivendev/Ahoy/blob/master/src/Swashbuckle.SwaggerUi/CustomAssets/index.html

copy this the /wwwroot as index.html add custom.css and ref in the html page. add h1