ASP.NET Core-Swashbuckle不创建swagger.json文件


75

我在获取Swashbuckle.AspNetCore(1.0.0)包来生成任何输出时遇到麻烦。我阅读了swagger.json文件,应将其写入“〜/ swagger / docs / v1”。但是,我没有得到任何输出。

我从一个全新的ASP.NET Core API项目开始。我应该提到这是ASP.NET Core2。该API可以正常工作,并且我可以从值控制器中检索值。

我的启动类的配置与本文(GitHub上的Swashbuckle.AspNetCore)完全相同。

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();
    }
}

您可以看到NuGet参考...

在此处输入图片说明

同样,这是所有默认模板,但我包括ValuesController供参考...

[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)
    {
    }
}

您在Visual Studio中的输出
胡沙姆hemaily

Answers:


48

我相信您错过了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");
    });
}

要访问Swagger UI,URL应为:http:// localhost:XXXX / swagger /

JSON可以在Swagger UI的顶部找到:

在此处输入图片说明


3
我实际上在env.IsDevelopment行上方有app.UseSwagger,但我将其移至该部分并添加了app.UseSwaggerUI。同样的问题。仍然没有输出。我更新了问题以反映新代码。
John Livermore

6
现在我也很烦。我不知道它是否实际上创建了一个文件,或者它是否只是在运行时生成了json而没有保存它。
TiagoBrenck,

17
为避免IIS别名出现问题,请从URL路径中删除/ swagger /。看起来应该像这样:app.UseSwaggerUI(c => {c.SwaggerEndpoint(“ v1 / swagger.json”,“ API name”);});
77bee6-5445-4c77-b1eb-4df3e5

3
谢谢@ 2b77bee6-5445-4c77-b1eb-4df3e5; 对我来说效果很好。
Appulus

1
@Eru Glad很有帮助,我刚刚将其添加为答案
2b77bee6-5445-4c77-b1eb-4df3e5

52

我有同样的问题。检查http:// localhost:XXXX / swagger / v1 / swagger.json。如果遇到任何错误,请修复它们。

例如,我在基本控制器类中有一条歧义的路由,但出现错误:“歧义的HTTP方法进行操作。行为需要Swagger 2.0的显式HttpMethod绑定。” 如果使用基本控制器,请确保您的公共方法使用HttpGet / HttpPost / HttpPut / HttpDelete或Route属性来避免路由不明确。

然后,我也用相同的方法定义了HttpGet(“ route”)和Route(“ route”)属性,这是大摇大摆的最后一个问题。


3
哦,你的第一段救了我〜!我意识到不存在swagger.json的原因是因为我的API控制器中存在一些错误,阻止了swagger生成json文件。修复所有错误后,迅速的用户界面又回来了!通过查看swagger.json的URL点,它会引发错误,这对于解决此问题确实很有帮助!!!
弗朗瓦

2
我遇到了同样的问题,我的删除端点之一没有完全实现,而是使用Route属性。一旦将该端点的Route属性更改为HttpDelete,该错误就消失了。感谢@Marisol
Hari Krishna Gaddipati

33

如果您的应用程序托管在IIS / IIS Express上,请尝试以下操作:

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

为我工作,谢谢
user1487912

22
#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

部署到IIS webapi(基本URL)时是应用程序别名。您需要为所有IIS部署保持Application Alias(基本URL)相同,因为swagger在“ /swagger/v1/swagger.json”位置查找swagger.json,但不会在应用程序Alias(基本URL)之前添加前缀,这就是它无法正常工作的原因。

例如:

本地主机/swagger/v1/swagger.json-找不到swagger.json


最好使用SwaggerUIOptions.RoutePrefix来定义webapi前缀(使用配置中的值),而不是对其进行硬编码。
oleksa

19

我陷入了一个相似但又不完全相同的问题。希望这可以帮助其他人。

我使用的是自定义文档标题,没有更改SwaggerEndPoint中的文件夹路径以匹配文档标题。如果将端点指向swagger / v1 / swagger.json,它将在swagger UI中找不到json文件。

例:

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");
});

15

您必须遵守2条规则:

  1. 装饰有明确的HTTP方法像所有的动作[HttpGet("xxx")][HttpPost("xxx")]或...代替[Route("xxx")]
  2. [NoAction]Attribute装饰控制器中的公共方法。

请注意,http:// localhost:XXXX / swagger /页面请求http:// localhost:XXXX / swagger / v1 / swagger.json文件,但是如果您不遵守上述规则,则Swagger会发生异常。


对我来说足够只需添加[NonAction],用[Route("xxx")]
奥列格嘘

13

在查看了答案并检查了建议之后,我最终不知道出了什么问题。

我真的尝试了一切。因此,如果最终遇到同样的情况,请了解问题可能是其他原因,与大张旗鼓完全无关。

就我而言是一个OData例外。

步骤如下:

1)导航到localhost:xxxx/swagger
2)打开开发人员工具
3)单击控制台中显示的错误,您将看到导致问题的内部异常。


1
同样在这里,开发人员工具向我展示了该路径指向的是localhost根目录,而不是默认站点下的特定应用程序
Peter PitLock

9

我将自己的评论移至答案,因为它似乎很有帮助。


为避免IIS别名出现问题,请从URL路径中删除/ swagger /。它看起来应该像这样:

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

6

如果控制器中有任何问题要映射到唯一URL,则会出现此错误。

查找问题原因的最佳方法是从项目中排除所有控制器。然后尝试通过一次启用一个控制器或一个控制器中的一个或多个方法来运行该应用程序,以查找有问题的控制器/控制器方法。或者,您可以变得聪明起来,并执行二进制搜索逻辑来查找禁用,然后启用多个控制器/方法来查找有问题的控制器/方法。

一些原因是

  1. 控制器中具有公共方法而没有HTTP方法属性

  2. 具有多个具有相同Http属性的方法,如果您不使用基于“ [action]”的映射,则可以映射到相同的api调用

  3. 如果使用版本控制,请确保在所有控制器版本中都具有该方法(即使使用继承,也要使用继承)


4

我们使用Swagger时常犯的一个常见错误是为(NET ASP)两个或多个路由赋予相同的名称。这会导致招摇无法生成JSON文件。例如,这是错误的方法

[HttpPost, Route("Start")]
public async Task<TransactionResult> WipStart(BodyWipStartDTO data)
{
    return await _wipServices.WipStart(data);
}

具有相同路径名称但不同动作名称的其他动作

[HttpPost, Route("Start")]
public async Task<TransactionResult> WipAbort(BodyWipStartDTO data)
{
    return await _wipServices.WipAbort(data);
}

这是正确的方法

[HttpPost, Route("Start")]
public async Task<TransactionResult> WipStart(BodyWipStartDTO data)
{
    return await _wipServices.WipStart(data);
}

[HttpPost, Route("Abort")]
public async Task<TransactionResult> WipAbort(BodyWipStartDTO data)
{
    return await _wipServices.WipAbort(data);
}

1
我有一个不带HttpMethod属性(HttpGet,HttpPost等)属性的控制器,该属性导致Actions require an explicit HttpMethod binding for Swagger
挥舞

2

就我个人而言,我遇到了同样的问题,当我在新版本(2.5.0)中发现一段时间后今天再次尝试使用json时,我可以看到此处错误的解释

另一个有助于解决此问题的方法是,删除连接到网站的托管信息,该网站位于解决方案文件夹根目录下的“ ..vs \ config \ applicationhost.config”中

我删除了配置网站的元素。

           <site name="**" id="9">
              <application path="/" applicationPool=""></application>
              <bindings></bindings>
           </site>

2

我在Post参数中使用内部类时遇到了这个问题

[HttpPost]
public async Task Post([FromBody] Foo value)
{
}

富在哪里

public class Foo
{
    public IEnumerable<Bar> Bars {get;set;}

    public class Bar
    {
    }
}

2

尝试按照以下步骤进行操作,既简单又干净。

  1. 检查您的控制台是否收到类似“ Ambiguous HTTP method for action. Actions require an explicit HttpMethod binding for Swagger 2.0.”的错误
  2. 如果:发生 此错误的原因:Swagger期望

每个端点都应具有方法(获取/发布/放入/删除)

解决方案

重新访问每个控制器,并确保已添加期望的方法。

(或者您只能在控制台错误中看到哪个控制器引起歧义)

  1. 如果如果发现任何问题,请告知我们。

1
在我的情况下,我错过了put方法[HttpPut]的注释,Swashbuckle丑陋地失败了,并且没有给出关于错误的解释。谢谢Unicoder。
豪尔赫·瓦尔维特

2

同样的问题-对我来说很容易解决。

为了找到潜在的问题,我导航到实际的swagger.json文件,该文件给了我真正的错误

/swagger/v1/swagger.json

此网址显示的实际错误是

NotSupportedException: Ambiguous HTTP method for action  ... Actions require an explicit HttpMethod binding for Swagger/OpenAPI 3.0

重点是

Actions require an explicit HttpMethod

然后,我用[HttpGet]装饰了控制器方法

[Route("GetFlatRows")]
 [HttpGet]
 public IActionResult GetFlatRows()
 {

问题解决了


2

我不知道这是否对某人有用,但是在我的情况下,问题是名字的大小写不同。

V1在服务配置中-设置中的V大写字母
v1-v小写

我唯一要做的就是使用相同的机壳,它确实有效。

版本名称,大写V


面临同样的问题。我发现在声明SwaggerDoc和SwaggerEndpoint配置时使用了不匹配的版本。在修复版本后,所有功能都可以正常工作。
Zhuravlev A.

1

使用版本标头而不是url版本控制创建api的版本2时,出现了Swagger错误。解决方法是将[Obsolete]属性添加到版本1方法中,然后SwaggerGeneratorOptionsStartup->ConfigureServices方法中用于忽略过时的api方法。

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


1

添加相对路径对我有用:

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

1

实际上,您只需要通过删除开头的反斜杠来修复swagger网址,如下所示:

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

代替 :

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

0

我遇到了同样的问题,并注意到我的API尚未托管在根文件夹和虚拟目录中。我将我的API移到了IIS中的根文件夹并开始工作。

此答案中的更多信息


0

确保拥有所有必需的依赖项,请转到url xxx / swagger / v1 / swagger.json,您可能会发现缺少一个或多个依赖项。

在此处输入图片说明


0

看一下Chrome开发人员工具,有时,swagger.json请求抛出http 500,女巫意味着您的控制器存在一些不一致之处。例如:在我的情况下,有一个“歧义HTTP操作方法”:

在此处输入图片说明


0

还有一个问题,因为我正在以IIS级别对应用程序进行版本控制,如下所示:

在此处输入图片说明

如果这样做,则Configure方法中的配置应附加如下所示的版本号:

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/1.0/swagger/V1/swagger.json", "Static Data Service");
});

0

当我尝试转到swagger.json URL位置时,我能够修复并了解我的问题:

https://localhost:XXXXX/swagger/v1/swagger.json

该页面将显示错误和找不到该错误的原因。

就我而言,我发现其中一个方法由于返回的错误而配置错误的XML定义:

NotSupportedException: HTTP method "GET" & path "api/Values/{id}" overloaded by actions - ...
...
...


0

您应将以下软件包安装到项目中。

5.0.0-rc4Swashbuckle的最低版本。否则,它将无法正常工作。

到目前为止,直接从Nuget安装它会安装旧版本,而这些旧版本不适用于Core 3。

我将以下几行插入.csproj项目文件中,如下所示:

<PackageReference Include="Microsoft.OpenApi" Version="1.1.4" />
<PackageReference Include="Swashbuckle.AspNetCore.Swagger" Version="5.0.0-rc4" />
<PackageReference Include="Swashbuckle.AspNetCore.SwaggerGen" Version="5.0.0-rc4" />
<PackageReference Include="Swashbuckle.AspNetCore.SwaggerUi" Version="5.0.0-rc4" />

之后,Rebuild将安装较新的版本。如果没有,您也可以使用还原。

在Startup.cs中,应按以下方式配置Swashbuckle:

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

            // Register the Swagger generator, defining 1 or more Swagger documents
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
            });

        services.AddMvc();
    }

 

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

        app.UseHttpsRedirection();

        // Enable middleware to serve generated Swagger as a JSON endpoint.
        app.UseSwagger();

        // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
        // specifying the Swagger JSON endpoint.
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
            //c.RoutePrefix = String.Empty;
        });

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }

只需转到“ https:// localhost:5001 / swagger / index.html ”,您将看到Swagger UI。(5001是我的本地端口,应使用您的端口进行更改)

我花了一点时间才弄清楚。

我希望它可以帮助其他人:)


0

回答:

If using directories or application  with IIS or a reverse proxy,<br/> set the Swagger endpoint to a relative path using the ./ prefix. For example,<br/> ./swagger/v1/swagger.json. Using /swagger/v1/swagger.json instructs the app to<br/>look for the JSON file at the true root of the URL (plus the route prefix, if used). For example, use http://localhost:<br/><br/><port>/<route_prefix>/swagger/v1/swagger.json instead of http://localhost:<br/><port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.<br/>
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");
//Add dot in front of swagger path so that it takes relative path in server
c.SwaggerEndpoint("./swagger/v1/swagger.json", "MyAPI V1");
    });
}

[Detail description of the swagger integration to web api core 3.0][1]


  [1]: https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.1&tabs=visual-studio

0

我遇到了一个愚蠢的问题,在AddSwaggerGen方法中使用大写字母v,在c.SwaggerEndpoint中使用小写字母v。

它似乎区分大小写。



0

我遇到了相同的错误,但是由于问题不同,我正在使用引起此问题的第三方库,因此我无需在该库中使用该库,因此我使用了此处发布的以下解决方案。

使用以下内容创建某个地方的类ApiExplorerIgnores

public class ApiExplorerIgnores : IActionModelConvention
{
    public void Apply(ActionModel action)
    {
        if (action.Controller.ControllerName.Equals("ImportExport"))
            action.ApiExplorer.IsVisible = false;
    }
}

在Startup.cs中的方法ConfigureServices中添加以下代码

services.AddMvc(c => c.Conventions.Add(new ApiExplorerIgnores()))

这将读取该控制器中的所有方法,您也可以使用特定级别,例如方法名称左右,也可以仅删除一个方法,等等。

By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.