标签: swagger

我尝试使用以下路径创建一个swagger文件:paths:/ v1/customers/{id}/summary:

但是我马上得到以下错误:

API需要路径参数,但未定义:路径id/v1/customers/{id}/summary中的id

它似乎不喜欢'id'参数.谁能告诉我如何纠正这个问题？

如果我深入研究这个,我会看到以下内容:

Details
 Object
 swaggerError: Object
 errors: Array [1]
 0: Object
code:  "MISSING_API_PATH_PARAMETER"
message:  "API requires path parameter but it is not defined: id"
data:  "/v1/customers/{id}/summary"
 path: Array [2]
 warnings: Array [0]

在Swagger中,不推荐使用@Api注释description.

有没有更新的方式来提供描述？

我有一个Keycloak受保护的后端,我想通过swagger-ui访问.Keycloak本身提供了oauth2隐式和accessCode流程,但我都没有工作.目前Keycloak的文档缺乏这一点,哪些url应该用于swagger.json中的authorizationUrl和tokenUrl.

Keycloak中的每个领域都通过访问http://keycloak.local/auth/realms/REALM/.well-known/openid-configuration提供了大量的配置URL列表.

此外,我试图通过添加以下行直接在swagger-ui index.html中集成keycloak js-client:

<script src="keycloak/keycloak.js"></script>
<script>
  var keycloak = Keycloak('keycloak.json');
    keycloak.init({ onLoad: 'login-required' })
      .success(function (authenticated) {
        console.log('Login Successful');
        window.authorizations.add("oauth2", new ApiKeyAuthorization("Authorization", "Bearer " + keycloak.token, "header"));
      }).error(function () {
        console.error('Login Failed');
        window.location.reload();
      }
    );
 </script>

"登录成功"后我也尝试了类似的东西

swaggerUi.api.clientAuthorizations.add("key", new SwaggerClient.ApiKeyAuthorization("Authorization", "Bearer " + keycloak.token, "header"));

但它也行不通.

有什么建议我如何能够在swagger中集成keycloak auth？

我正在尝试将我的API文档分解为多个可以独立编辑的JSON文件.我能够找到的所有示例都使用Swagger 1.2模式,该模式具有"api":{}对象以便将其分解.这似乎在2.0模式(http://json.schemastore.org/swagger-2.0)中缺失.所有定义的都是单个"路径"数组,它将所有API端点捆绑到该单个数组中.这在swagger-ui中的效果是有一个单独的"默认"类别,所有内容都被捆绑在一起,我无法分辨它.

TLDR:如何从swagger 2.0模式中的路径中拆分操作

{
  "swagger": "2.0",
  "info": {
    "description": "My API",
    "version": "1.0.0",
    "title": "My API",
    "termsOfService": "http://www.domain.com",
    "contact": {
      "name": "support@domain.com"
    }
  },
  "basePath": "/",
  "schemes": [
    "http"
  ],
  "paths": {
    "Authorization/LoginAPI": {
      "post": {
        "summary": "Authenticates you to the system and produces a session token that will be used for future calls",
        "description": "",
        "operationId": "LoginAPI",
        "consumes": [
          "application/x-www-form-urlencoded"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [{
          "in": "formData",
          "name": "UserName",
          "description": "Login Username",
          "required": true, …

我正在寻找一个可以帮助我生成RESTful API文档的工具.我的服务器是用Java编写的,并使用Spring MVC框架.我的服务器中没有VIEWS.它是一个100%RESTful服务,它所做的只是消耗JSON并吐出JSON.

我想知道Swagger是否与Spring注释兼容？

我熟悉Microsoft堆栈.我正在使用OData来完成我的一些宁静服务.最近我遇到了Swagger的API文档,我试图了解它与OData的关系.它们似乎都是RESTful规范.哪一个被广泛使用？

我想格式化我的Swagger API描述,以便它们不是简单的文本段落.最好,我想为它添加一个小桌子.

我没有在Swagger描述中找到有关文本格式的在线参考.如果我启动Swagger编辑器,并打开Instagram示例(File\Open Example\Instagram.yaml),我看到yaml文件中的第一个描述显示了一些格式,包括超链接和边界框:

    [registered your client](http://instagram.com/developer/register/) it's easy
to start requesting data from Instagram.

```
  https://api.instagram.com/v1/media/popular?client_id=CLIENT-ID
```

这看起来像标准的Markdown,但是当我在样本描述中添加表markdown时,编辑器会出现错误:

|Col1|Col2|
|------|------|
|1|2|


YAML Syntax Error
End of the stream or a document separator is expected at line 36, column

Swagger 2.0允许什么格式化？我做错了呈现一张桌子吗？

我正在使用Swashbuckle为webapi2项目生成swagger文档\ UI.我们的模型与一些传统接口共享,因此我想在模型上忽略一些属性.我不能使用JsonIgnore属性,因为旧版接口也需要序列化为JSON,所以我不想全局忽略这些属性,只是在Swashbuckle配置中.

我在这里找到了一种记录方法:

https://github.com/domaindrivendev/Swashbuckle/issues/73

但这似乎与目前的Swashbuckle版本已经过时了.

为旧版Swashbuckle推荐的方法是使用IModelFilter实现,如下所示:

public class OmitIgnoredProperties : IModelFilter
{
    public void Apply(DataType model, DataTypeRegistry dataTypeRegistry, Type type)
    {
        var ignoredProperties = … // use reflection to find any properties on 
                                  // type decorated with the ignore attributes

        foreach (var prop in ignoredProperties) 
            model.Properties.Remove(prop.Name);

    }
}

SwaggerSpecConfig.Customize(c => c.ModelFilter<OmitIgnoredProperties>());

但我不确定如何配置Swashbuckle在当前版本中使用IModelFilter？我正在使用Swashbuckle 5.5.3.

我有以下YAML片段:

description: |
  "API for bean consuming applications.
  Examples: painted pony, lima bean"

:尽管有引号,但Swagger编辑器将冒号()解释为特殊字符.

根据这个问题的公认答案,结肠不应该被视为特殊性质.

这是Swagger的错误还是在引用的文本文字中使用冒号所需的转义序列？

我尝试使用YAML规范找到它但放弃了.

我如何阅读该规范来回答这个问题？

YAML中的单引号(')和双引号(")之间有区别吗？

pipe(|)或大于(>)结构是否仅影响换行处理或特殊字符的处理？

我创建了一个使用个人帐户安全的asp.net webapi应用程序,以便默认启用Bearer令牌.它工作正常,所以我能够在Postman中测试它们没有问题.

当我尝试通过Swashbuckle集成Swagger UI时,问题就出现了.我通过以下方式安装了Swashbuckle:

Install-Package Swashbuckle

然后更改SwaggerConfig.cs:

GlobalConfiguration.Configuration
    .EnableSwagger(c =>
    {
        c.ApiKey("Token")
            .Description("Filling bearer token here")
            .Name("Authorization")
            .In("header");
    }
    .EnableSwaggerUi(c =>
    {
        c.EnableApiKeySupport("Authorization", "header");
    };

启动我的应用程序并填写Bearer令牌:

但是当我运行需要授权的api请求时,它不起作用.这是截图:

承载令牌被添加到标头中的Authorization.但我仍然得到错误401.我想知道是否因为令牌被编码(SPACE被%20取代)？任何的想法？谢谢.

顺便说一句,我想知道如何在我的Swagger文档中添加/ token,以便我可以在Swagger UI中获取令牌.