ASP.NET Core - Swashbuckle not creating swagger.json file

Question

I am having trouble getting the Swashbuckle.AspNetCore (1.0.0) package to generate any output. I read the swagger.json file should be written to '~/swagger/docs/v1'. However, I am not getting any output.

I started with a brand new ASP.NET Core API project. I should mention this is ASP.NET Core 2. The API works, and I am able to retrieve values from the values controller just fine.

My startup class has the configuration exactly as described in this article (Swashbuckle.AspNetCore on GitHub).

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    // This method gets called by the runtime. Use this method to add services to the container.
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();

        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
        });
    }

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();

            // Enable middleware to serve generated Swagger as a JSON endpoint.
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "MyAPI V1");
            });
        }
        else
        {
            app.UseExceptionHandler();
        }

        app.UseStatusCodePages();
        app.UseMvc();

        //throw new Exception();
    }
}

You can see the NuGet references...

Again, this is all the default template, but I include the ValuesController for reference...

[Route("api/[controller]")]
public class ValuesController : Controller
{
    // GET api/values
    [HttpGet]
    public IEnumerable<string> Get()
    {
        return new string[] { "value1", "value2" };
    }

    // GET api/values/5
    [HttpGet("{id}")]
    public string Get(int id)
    {
        return "value";
    }

    // POST api/values
    [HttpPost]
    public void Post([FromBody]string value)
    {
    }

    // PUT api/values/5
    [HttpPut("{id}")]
    public void Put(int id, [FromBody]string value)
    {
    }

    // DELETE api/values/5
    [HttpDelete("{id}")]
    public void Delete(int id)
    {
    }
}

Solution 1

I believe you missed these two lines on your Configure:

if (env.IsDevelopment())
{
    app.UseDeveloperExceptionPage();

    // Enable middleware to serve generated Swagger as a JSON endpoint.
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("v1/swagger.json", "MyAPI V1");
    });
}

To access Swagger UI, the URL should be: http://localhost:XXXX/swagger/

The json can be found at the top of Swagger UI:

Solution 2

I had the same problem. Check http://localhost:XXXX/swagger/v1/swagger.json. If you get any a errors, fix them.

For example, I had an ambiguous route in a base controller class and I got the error: "Ambiguous HTTP method for action. Actions require an explicit HttpMethod binding for Swagger 2.0.". If you use base controllers make sure your public methods use the HttpGet/HttpPost/HttpPut/HttpDelete OR Route attributes to avoid ambiguous routes.

Then, also, I had defined both HttpGet("route") AND Route("route") attributes in the same method, which was the last issue for swagger.

Solution 3

If your application is hosted on IIS/IIS Express try the following:

c.SwaggerEndpoint("../swagger/v1/swagger.json", "MyAPI V1");

Solution 4

#if DEBUG
   // For Debug in Kestrel
   c.SwaggerEndpoint("/swagger/v1/swagger.json", "Web API V1");
#else
   // To deploy on IIS
   c.SwaggerEndpoint("/webapi/swagger/v1/swagger.json", "Web API V1");
#endif

When deployed to IIS webapi(base URL) is the Application Alias. You need to keep Application Alias(base URL) same for all IIS deployments because swagger looks for swagger.json at "/swagger/v1/swagger.json" location but wont prefix application Alias(base URL) that is the reason it wont work.

For Example:

localhost/swagger/v1/swagger.json - Couldn't find swagger.json

Solution 5

I was running into a similar, but not exactly the same issue with swagger. Hopefully this helps someone else.

I was using a custom document title and was not changing the folder path in the SwaggerEndPoint to match the document title. If you leave the endpoint pointing to swagger/v1/swagger.json it won't find the json file in the swagger UI.

Example:

services.AddSwaggerGen(swagger =>
{
    swagger.SwaggerDoc("AppAdministration", new Info { Title = "App Administration API", Version = "v1.0" });
            
});


app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/AppAdministration/swagger.json", "App Administration");
});

View more solutions

Comments

[John Livermore]

I actually had the app.UseSwagger above the env.IsDevelopment line, but I moved it into that section and added the app.UseSwaggerUI. Same issue. No output still. I updated my question to reflect the new code.

[Tiago B]

@JohnLivermore, in order to access swagger, your URL should be localhost:xxxx/swagger. What is the error when you access it?

[John Livermore]

Oh, well that actually worked! Still no swagger.json in the directory I was expecting to find it. Where is that stored?

[Tiago B]

On top of the Swagger UI, there is the path of you .json file

[John Livermore]

Correct. I understand it's supposed to be there, but it's not. I searched my entire hard drive for swagger and it didn't return any swagger.json files. I would expect to see it in {webroot}/swagger/v1/swagger.json, but it's not there. Just trying to make sure I know how this works!

[Tiago B]

Now I am also bugged. I dont know if it actually creates a file, or if it just generates the json on the fly and dont save it.

[K. Akins]

Same issue here, any solution? I know my Startup.cs is correct.

[Mohan Gopi]

I am getting same issue. Can any one suggest on this.

[2b77bee6-5445-4c77-b1eb-4df3e5]

To avoid issues with IIS aliases, remove /swagger/ from the URL path. It should look like this: app.UseSwaggerUI(c => { c.SwaggerEndpoint("v1/swagger.json", "API name"); });

[Appulus]

Thanks @2b77bee6-5445-4c77-b1eb-4df3e5; that worked perfectly for me.

[Franva]

hi @JohnLivermore, I'm facing the same issue. How did you solve your problem? Please help!

[Franva]

oh man, your frist paragraph saved me~! I realized that the reason why the swagger.json was not there was because that there were some errors in my API Controller which prevented the swagger to generate the json file. Once I fixed all errors, the swagger UI was back~! By looking into the url points to swagger.json, it throws errors which is really helpful for fixing the issue!!!

[Hari Krishna Gaddipati]

I had the same issue, One of my delete endpoints is not completely implemented and uses Route attribute. Once I changed the Route attribute to HttpDelete for that endpoint, the error is gone. Thanks @Marisol

[Oleg Sh]

for me enough just add [NonAction], with [Route("xxx")]

[Peter PitLock]

Same here, Developer tools showed me that the path was pointing to the localhost root as opposed to the specific app under default site

[oleksa]

it would be better to use the SwaggerUIOptions.RoutePrefix to define the webapi prefix (using a value from the config) rather than having it hardcoded.

[oleksa]

I had a controller without HttpMethod attribute (HttpGet, HttpPost etc) attributes on the methods that caused swagger to fail with Actions require an explicit HttpMethod binding for Swagger

[Jorge Valvert]

In my case I missed the annotation for the put method [HttpPut], Swashbuckle fails ugly and doesn't give an explanation about the error. Thanks Unicoder.

[Eru]

@2b77bee6-5445-4c77-b1eb-4df3e5 it also worked for me! I think you should make a full reply to this topic with your helpful answer :)

[2b77bee6-5445-4c77-b1eb-4df3e5]

@Eru Glad it was helpful, I have just added it as an answer

[Karel Frajták]

My case - I have canceled/dismissed the Firewall dialog about the port my app was running on and was not getting any output and the error displayed was screaming at me "ERROR_UNSAFE_PORT" ...

[Veve]

Please add an explaination to your answer in regards to the question asked.

[Zhuravlev A.]

Faced with the same problem. I found I used mismatching versions when declaring SwaggerDoc and SwaggerEndpoint configuration. After I fixed versions all started to work fine.

[Zoey]

I had two HTTPGET's, different signatures but once I removed my new one my error went away.

[Jason Snelders]

I'm working on a .NET 5 Controller with OnActionExecuting()/OnActionExecuted() implemented agaisnt IActionFilter, and adding the [NonAction] attribute to those method did the trick for me.

[Jason Snelders]

@MohammadBarbast Just for clarification, I used [NonAction] rather than [NoAction] (in your second bullet) because the [NoAction]attribute does not exist in .NET 5 (not sure if you have a typo or it used to exist in previous Core versions and was changed).

[Ramiro G.M.]

After taking a look at the web console I figured out the document creation was crashing because I had two different entry models with the same name. Thanks for pointing in the right direction mate.

[Robert P]

On top of this, if you don't get an exception back, but just a 500 error, you may still be getting an exception that's hidden. When running in debug mode turn on all CLR errors, and you should be able to find the details of the error.

[Robert P]

In addition, the error might not actually show up in your browser. Run your application in debug mode, and turn on breaking on all CLR exceptions. When you load the swagger.json URL, the exception will be thrown and shown to you. This should contain the details of why the swagger.json file isn't being generated.

[Nikola Novak]

Wow, that seems random. (And it worked in my case, thanks.)

[Triet Nguyen]

Thanks for this. This is actually the best answer. SwaggerDoc(name) must be the same with value of SwaggerDoc(OpenApi -> Version) & SwaggerEndpoint(url) also. Hence SwaggerUI will route to correct swagger file

[Saurabh]

only answer that worked. Thanks a lot. Can you please also elaborate the reason in detail please