使用swagger生成API的json文件

WindySky 2017-09-14

展开全文

使用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://</url>
                                    </contact>
                                    <license>
                                        <url>http://www./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>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

官网给的版本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>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20