0

好的，所以我的 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}}

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

4

1 回答 1

1

将插件更新到最新版本，即 3.1.0，您会得到很好的服务。看这里：

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

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

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

于 2015-08-27T04:44:07.543 回答