Swagger parsing fails due to format suffix generated by swagger-maven-plugin

Question

Alright, so my Swagger docs are generated using:

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

Which ends up generating

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

The issue I am running into is when I attempt to use the SwaggerLegacyParser provided by swagger, to get the Resource Listing, I get an error due to the .{format} being part of the listing. Even if I try hitting the /service.json path, the .{format} remains. This issue that gets thrown is thrown from JsonSchema's doValidate method and the message is

"message" : "string \"/v1/api.{format}\" is not a valid URI"

which from my digging is because { and } are invalid URI characters. This validation is kicked off on line 44 of SwaggerLegacyParser in the swagger parser's attached source to version 1.0.10.

The output template is:

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

Anyone have ideas on how to help? Are my docs wrong or am I using the parser wrong?

Answer 1

you will be well served by updating the plugin to the latest, which is 3.1.0. See here:

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

Swagger spec has undergone 2 revisions since the 2.2 version that you're referencing. This will bring you up to speed with the spec changes and the tooling that comes with it.

The .{format} should technically be supported though. I'm suspecting there is more information that you can give to help sort this out, and happy to help with that. But you will bypass this completely with the latest plugin version.