使用swagger生成API的json文件

使用swagger生成API的json文件

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

---

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

1. 在pom.xml中添加plugin

                <plugin>
                    <groupId>com.github.kongchengroupId>
                    <artifactId>swagger-maven-pluginartifactId>
                    <version>3.1.0version>
                    <configuration>
                        <apiSources>
                            <apiSource>
                                <springmvc>falsespringmvc> 
                                <locations>com.rooyeetone.rtprest.restlocations>
                                <schemes>http,httpsschemes>
                                <host>petstore.swagger.wordnik.comhost>
                                <basePath>/rtprest/restbasePath>
                                <info>
                                    <title>RTP REST APIstitle>
                                    <version>v1version>
                                    <description>This is a sample for swagger-maven-plugindescription>
                                    <termsOfService>
                                        http://www.github.com/kongchen/swagger-maven-plugin
                                    termsOfService>
                                    <contact>
                                        <email>[email protected]email>
                                        <name>Kong Chenname>
                                        <url>http://kongch.comurl>
                                    contact>
                                    <license>
                                        <url>http://www.apache.org/licenses/LICENSE-2.0.htmlurl>
                                        <name>Apache 2.0name>
                                    license>
                                info>
                                <templatePath>${basedir}/src/main/resources/templates/strapdown.html.hbstemplatePath>
                                <outputPath>${basedir}/src/main/resources/generated/document.htmloutputPath>
                                <swaggerDirectory>${basedir}/src/main/resources/generated/swagger-uiswaggerDirectory>


                            apiSource>
                        apiSources>
                    configuration>
                    <executions>
                        <execution>
                            <phase>compilephase>
                            <goals>
                                <goal>generategoal>
                            goals>
                        execution>
                    executions>
                plugin>

1. 官网给的版本3.0.1没下载到,所以换为3.1.0,等maven下载完依赖可能会报错,在标签处会提示错误,可以选择quickfix,ignore,然后打开lifecycle-mapping-metadata.xml文件,将标签修改,完整xml如下

   
   <lifecycleMappingMetadata>
   <pluginExecutions>
       <pluginExecution>
           <pluginExecutionFilter>
               <groupId>com.github.kongchengroupId>
               <artifactId>swagger-maven-pluginartifactId>
               <versionRange>3.1.0versionRange>
               <goals>
                   <goal>generategoal>
               goals>
           pluginExecutionFilter>
           <action>
               <execute>
                   <runOnIncremental>truerunOnIncremental>
               execute>
           action>
       pluginExecution>
   pluginExecutions>
   lifecycleMappingMetadata>

2. maven update ,然后执行命令 mvn clean compile

3. 查看生成的json吧,如果如果只有swagger的info,那么需要注意plugin3.1.0对应的swagger版本为新版,使用的注解应同时存在@Api和@Path
4. wan,有时间再补充吧