【问题标题】:Swagger parsing fails due to format suffix generated by swagger-maven-plugin由于 swagger-maven-plugin 生成的格式后缀,Swagger 解析失败
【发布时间】:2015-11-21 02:18:58
【问题描述】:

好的,所以我的 Swagger 文档是使用以下工具生成的:

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>2.2</version>
    <configuration>
        <apiSources>
            <apiSource>
                <locations>com.example.service.rest.ws</locations>
                <apiVersion>v1</apiVersion>
                <basePath>https://localhost:8080/service/rest</basePath>
                <outputTemplate>
                    ${basedir}/src/main/resources/markdown.mustache
                </outputTemplate>
                <outputPath>${project.build.directory}/generated-apis/apidocs/strapdown.html</outputPath>
                <swaggerUIDocBasePath />
                <swaggerDirectory>${project.build.directory}/generated-apis/apidocs</swaggerDirectory>
                <useOutputFlatStructure>false</useOutputFlatStructure>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

最终生成

{
    "apiVersion" : "v1",
    "swaggerVersion" : "1.2",
    "apis" : [ {
        "path" : "/v1/api.{format}",
        "description" : "Service"
    } ]
}

我遇到的问题是,当我尝试使用 swagger 提供的 SwaggerLegacyParser 来获取资源列表时,由于 .{format} 是列表的一部分,我收到一个错误。即使我尝试点击 /service.json 路径, .{format} 仍然存在。抛出的这个问题是从 JsonSchema 的 doValidate 方法抛出的,消息是

"message" : "string \"/v1/api.{format}\" 不是有效的 URI"

我的挖掘是因为 { 和 } 是无效的 URI 字符。此验证在 swagger 解析器附加到版本 1.0.10 的源中的 SwaggerLegacyParser 的第 44 行开始。

输出模板为:

#API Document


## BasePath: {{basePath}}

## Api Version: {{apiVersion}}

## Resources
{{#apiDocuments}}
### {{index}}. {{resourcePath}}
#### Overview
{{{description}}}

{{#apis}}
#### {{index}}.{{apiIndex}} `{{path}}`
{{#operations}}
##### {{index}}.{{apiIndex}}.{{opIndex}} {{nickname}}
**{{httpMethod}}** `{{path}}`

{{summary}}
{{{notes}}}

###### URL
    {{url}}
###### Parameters
{{#parameters}}
- {{paramType}}

    <table border="1">
        <tr>
            <th>Parameter</th>
            <th>Required</th>
            <th>Description</th>
            <th>Data Type</th>
        </tr>
        {{#paras}}
        <tr>
            <th>{{name}}</th>
            <td>{{required}}</td>
            <td>{{description}}</td>
            <td>{{#linkType}}<a href="#{{linkType}}">{{type}}</a>{{/linkType}}{{^linkType}}{{type}}{{/linkType}}</td>
        </tr>
        {{/paras}}
    </table>
{{/parameters}}

{{#responseClass}}
###### Response
[{{className}}](#{{classLinkName}}){{^genericClasses}}{{/genericClasses}}{{#genericClasses}}< [{{className}}](#{{classLinkName}}) >{{/genericClasses}}
{{/responseClass}}


###### Errors
<table border="1">
    <tr>
        <th>Status Code</th>
        <th>Reason</th>
    </tr>
    {{#errorResponses}}
        <tr>
            <td>{{code}}</td>
            <td>{{message}}</td>
        </tr>
    {{/errorResponses}}
</table>

{{#samples}}
###### Samples
{{/samples}}
{{#samples}}
{{sampleDescription}}

- Sample Request

```
{{{sampleRequest}}}
```

- Sample Response

```
{{{sampleResponse}}}
```

{{/samples}}

- - -
{{/operations}}
{{/apis}}
{{/apiDocuments}}

## Data Types
{{#dataTypes}}


## <a name="{{name}}">{{name}}</a>

<table border="1">
    <tr>
        <th>type</th>
        <th>required</th>
        <th>access</th>
        <th>description</th>
        <th>notes</th>
    </tr>
    {{#items}}
        <tr>
            <td>{{#linkType}}<a href="#{{linkType}}">{{type}}</a>{{/linkType}}{{^linkType}}{{type}}{{/linkType}}</td>
            <td>{{#required}}required{{/required}}{{^required}}optional{{/required}}</td>
            <td>{{#access}}{{{access}}}{{/access}}{{^access}}-{{/access}}</td>
            <td>{{#description}}{{{description}}}{{/description}}{{^description}}-{{/description}}</td>
            <td>{{#notes}}{{{notes}}}{{/notes}}{{^notes}}-{{/notes}}</td>
        </tr>
    {{/items}}
</table>

{{/dataTypes}}

有人对如何提供帮助有想法吗?是我的文档有误还是我使用的解析器有误?

【问题讨论】:

    标签: swagger swagger-maven-plugin


    【解决方案1】:

    将插件更新到最新版本,即 3.1.0,您会得到很好的服务。见这里:

    https://github.com/kongchen/swagger-maven-plugin

    自您引用的 2.2 版本以来,Swagger 规范经历了 2 次修订。这将使您快速了解规范更改和随之而来的工具。

    .{format} 应该在技术上得到支持。我怀疑您可以提供更多信息来帮助解决这个问题,并且很乐意提供帮助。但是你会用最新的插件版本完全绕过这个。

    【讨论】:

    • 还有很多其他的东西依赖于我们的 swagger 文档,所以为了方便不更新它们,我宁愿保留它们的版本,因为我们目前根据 1.2 规范生成文档在其他地方使用。至于其他信息,我已经编辑了主要帖子以包含有关失败的更多细节。
    • 如果你能分享你的spec文件,这个问题就可以解决。
    • 我不确定哪个文件在技术上是规范文件,但我继续添加了输出模板,这似乎对您的暗示有意义。感谢您的帮助!
    猜你喜欢
    • 1970-01-01
    • 2020-04-05
    • 2021-05-31
    • 2017-04-15
    • 1970-01-01
    • 1970-01-01
    • 2022-10-20
    • 2016-08-13
    • 1970-01-01
    相关资源
    最近更新 更多