Rules to Better OpenAPI Specification

​​​​AKA OAS. Previously known as Swagger.

Hold on a second! How would you like to view this content?
Just the title! A brief blurb! Gimme everything!
  1. Do you use the best OpenAPI toolchain?

    Know the best OpenAPI toolchain:

    ​swashbuckle

    ​​​​​Bad Example ​​

    nswag

    ​​​Good Example (more comprehensive)
  2. Do you give a developer an API help page?

    www.northwind.com/swagger 

    Bad example - default but now it is about help for your API)​​

    www.northwind.com/dev​
    OR​
    www.northwind.com/developer

    Bad example​​s

    www.northwind.com/api  

    Bad example - already taken

    www.northwind.com/help 

    Bad example - too broad

    www.northwind.com/docs 

    Good example - preferred URL​
  3. Do you automate the generation of your API specification and required clients?

    If your changes to your WebAPI break your client, then you want to know right away.

    Using NSwag you should generate your API client eg. Angular Client.

    • You run nswag.exe on the post-build event
    • Nswag will generate the client code and update the API client file directly
    using-nswag-helps-automation.jpg
    Figure: Good example – using NSwag config file helps with automation. Since the API client is generated automatically next time we build, any breaking changes will be obvious immediately

    Now this is automated this is no longer a concern we need to deal with.

    More info: http://www.codingflow.net/building-single-page-applications-on-asp-net-core-2-1-with-angular-6-part-3-implementing-open-api/

  4. Do you define your response types?

    It is important to define your response types.

    bad-no-response-types.jpg
    dd>​Figure: Bad example – no response types
    good-response-types.png
    Figure: Good example – Response types (in .NET)


    /// <summary>
    /// Returns the nth number in the fibonacci sequence.
    /// </summary>
    /// <param name="n">The index (n) of the fibonacci sequence</param>
    /// <returns>Returns the nth fibonacci number.</returns>
    /// <response code="200">int64</response>
    [HttpGet]
    [ProducesResponseType(200)]
    [ProducesResponseType(400)]
    [ResponseCache(CacheProfileName = DefaultCacheProfile.Name)]
    [Produces("application/json", "text/json")]
    public ActionResult<long> Get(long n)
    {
    _logger.LogInformation($"Fibonacci number {n} requested");
    if(!_fibonacciSolver.CanSolve(n))
    return new BadRequestResult();
    try
    {
    return _cache.GetOrAdd($"Fibonacci{n}", () => _fibonacciSolver.Solve(n));
    }
    catch (ArgumentOutOfRangeException)
    {
    return new BadRequestResult();
    }
    }

    Figure: Good example for swashbuckle - Even b​etter if you have .NET Core 2.1 use the strong typed ActionResult – see yellow​​

            [HttpGet]
            [SwaggerResponse(HttpStatusCode.OK, typeof(long))]
            [SwaggerResponse(HttpStatusCode.BadRequest, typeof(void))]
            public ActionResult<long> Get(long n)
            {
                _logger.LogInformation($"Fibonacci number {n} requested");
                
                if(!_fibonacciSolver.CanSolve(n))
                    return new BadRequestResult();
     
                try
                {
                    return _cache.GetOrAdd($"Fibonacci{n}", () => _fibonacciSolver.Solve(n));
                }
                catch (ArgumentOutOfRangeException)
                {
                    return new BadRequestResult();
                }
            }

    Figure: Good example for nswag - Even better if you have .NET Core 2.1 use the strong typed ActionResult – see yellow​​