使用swagger生成API的json文件

使用swagger生成API的json文件

使用swagger可以方便的生成REST API,最近有机会了解一下,就记录下小小的踩坑经历吧.

demo使用maven搭建,REST采用jersey,swagger的版本选用了新版(即io.swagger),接着就是要用到的swagger-maven-plugin了.

在pom.xml中添加plugin

<plugin>
<groupId>com.github.kongchen</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>3.1.0</version>
<configuration>
<apiSources>
<apiSource>
<springmvc>false</springmvc> <!-- false为JAX-RS -->
<locations>com.rooyeetone.rtprest.rest</locations>
<schemes>http,https</schemes>
<host>petstore.swagger.wordnik.com</host>
<basePath>/rtprest/rest</basePath>
<info>
<title>RTP REST APIs</title>
<version>v1</version>
<description>This is a sample for swagger-maven-plugin</description>
<termsOfService> http://www.github.com/kongchen/swagger-maven-plugin </termsOfService>
<contact>
<email>kongchen@gmail.com</email>
<name>Kong Chen</name>
<url>http://kongch.com</url>
</contact>
<license>
<url>http://www.apache.org/licenses/LICENSE-2.0.html</url>
<name>Apache 2.0</name>
</license>
</info>
<templatePath>${basedir}/src/main/resources/templates/strapdown.html.hbs</templatePath>
<outputPath>${basedir}/src/main/resources/generated/document.html</outputPath>
<swaggerDirectory>${basedir}/src/main/resources/generated/swagger-ui</swaggerDirectory>
<!--                                <attachSwaggerArtifact>true</attachSwaggerArtifact> -->
<!--                                <jsonExampleValues>true</jsonExampleValues> -->
</apiSource>
</apiSources>
</configuration>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>

官网给的版本3.0.1没下载到,所以换为3.1.0,等maven下载完依赖可能会报错,在

<execution>

标签处会提示错误,可以选择quickfix,ignore,然后打开

lifecycle-mapping-metadata.xml

文件,将

<action>

标签修改,完整xml如下

<?xml version="1.0" encoding="UTF-8"?>
<lifecycleMappingMetadata>
<pluginExecutions>
<pluginExecution>
<pluginExecutionFilter>
<groupId>com.github.kongchen</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<versionRange>3.1.0</versionRange>
<goals>
<goal>generate</goal>
</goals>
</pluginExecutionFilter>
<action>
<execute>
<runOnIncremental>true</runOnIncremental>
</execute>
</action>
</pluginExecution>
</pluginExecutions>
</lifecycleMappingMetadata>

maven update ,然后执行命令

mvn clean compile

查看生成的json吧,如果如果只有swagger的info,那么需要注意plugin3.1.0对应的swagger版本为新版,使用的注解应同时存在

@Api

和

@Path

wan,有时间再补充吧