How can I use Swashbuckle's SwaggerUI to display a static swagger.json file instead of SwaggerGen's dynamically created definiton?

3
votes

I have an ASP.NET Core MVC application, targeting the .NET Core 2.1 framework. This application serves a RESTful API and returns JSON data.

Using the interactive, web-based SwaggerGen in SwaggerHub, I've created an API definition document and saved it in JSON format as 'swagger.json' in a folder in my ASP.NET Core MVC application project.

Manually created 'swagger.json' API definition file

Since I've already defined the API, I don't need to run SwaggerGen in my application. I'd just like SwaggerUI to display the static 'swagger.json' file I've created.

I've read the Swashbuckle documentation as well as several "How to get started with Swashbuckle" tutorials, but they all assume that SwaggerGen will be used to dynamically create the Swagger API documentation from my API.

I've added the 'Swashbuckle.AspNetCore' NuGet package to my application's dependencies.

Swashbuckle.AspNetCore NuGet package

In the Configure() method in my application's Startup.cs class, I've added the UseSwaggerUI directive:

app.UseSwaggerUI(c => {
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

When I run my application in Visual Studio, I get a normal blank page.

ASP.NET Core MVC application running

Per the Swashbuckle documentation, the SwaggerUI-formatted API documentation should be available at the relative '/swagger' path, assuming that SwaggerGen had been added and had dynamically generated the API definition (file?).

GETting the relative '/swagger' path produces a '400 Bad Request' error.

Requesting the Swagger documentation produces '400 Bad Request' error

Q: Would SwaggerGen produce its own 'swagger.json' file, and if so, where would it create this file?

Q: Is there a way to tell SwaggerUI where to find and display my manually created 'swagger.json' API definition file?

Thanks!

2
asp.net-core-mvcopenapiswashbuckle
Why would you even want to do this? Pretty much the whole point is to have the swagger.json generated automatically, so it's kept in sync with changes you make to your API. If you were to use a static swagger.json, you would also then need to remember to regen it any time you make a change, which I can assure you that you will not remember to do. Is this a performance thing? The JSON is only generated when it's requested, which means it's only going to impact the API docs, not your site as whole. Even then, it's not exactly arduous to gen. - Chris Pratt
Hi, @ChrisPratt. Swagger (well, SmartBear, actually) has a number of API-first tools, including one that can generate application source code from an API definition. If we generate code from an API definition, then we've flipped the "order of operations" and changed the priority from code to design. This also guarantees that changes to the API definition are never forgotten. They are made first and are what results in the source code. - Doug Wilson
Design first is a good approach. but @ChrisPratt makes us think Why would you want to do this? Swashbuckle is a sledgehammer to fix a swiss watch. Why use that? was that the "easy" NuGet package option? - Helder Sepulveda
@DougWilson I guest my point is that Swagger UI is just a SPA. If you're not combining it with the Gen, then it doesn't need to be part of your project at all. Just throw it up somewhere and feed it your static JSON files. Done. - Chris Pratt
@ChrisPratt, our use case is microservices, each with its own API definition. They are intended to run independently in Docker containers, so being self-contained and self-sufficient is important. I don't want to have to include a Node server just to display SwaggerUi documents, especially since Swashbuckle claims to do this from within ASP.NET Core MVC projects. - Doug Wilson

2 Answers

0
votes

  1. On your local machine, make a small node project, install swagger-ui-dist

  2. copy the installed files from node_modules/swagger-ui-dist to your webserver where you host the swagger site

  3. Copy your generated swagger.json to the same folder in your webserver

  4. Edit index.html and add the url to your json , ex. '/swagger.json'

  5. Done

Source

https://yanhan.github.io/posts/2017-11-26-using-swagger-ui-with-any-codebase/

1
votes

You can tell any Swagger-UI where to find the file using the url parameter:

And that is all you need, you can use any Swagger-UI no need to install swashbuckle if you already generate your definition with SwaggerHub.

If you want to host a Swagger-UI yourself just copy the dist folder to your webserver:
https://github.com/swagger-api/swagger-ui/tree/master/dist