使用swagger生成API的json文件

原创 2016年06月01日 09:54:21

使用swagger生成API的json文件

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


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

  1. 在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>
  1. 官网给的版本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>
  2. maven update ,然后执行命令 mvn clean compile

  3. 查看生成的json吧,如果如果只有swagger的info,那么需要注意plugin3.1.0对应的swagger版本为新版,使用的注解应同时存在@Api@Path
  4. wan,有时间再补充吧
版权声明:本文为博主原创文章,未经博主允许不得转载。

swagger使用笔记

在很多框架中,都会看到这个词汇, 这个组件,到底是干什么的呢?我所了解的swagger常见功能: 1. API文档生成工具,用户对系统中的API进行说明,以及提供测试接口. 2. 代码自动生成功能...
  • hzwy23
  • hzwy23
  • 2017年04月14日 22:53
  • 2322

swagger (可视化RESTful API的工具)

swagger 是一个可视化RESTful WebService的工具。 官网:http://swagger.io 效果 下图可以看出,swagger清晰地展现了web服务的方法、地址、发送json格...
  • chuchus
  • chuchus
  • 2015年04月13日 15:34
  • 10906

使用swagger 遇到 Can't read swagger JSON 错误

最近在做项目的过程中,使用到了swagger ,按照swagger 正常设置之后,在浏览器中查看接口的时候却遇到了 Can't read swagger JSON 错误,刚开始没有头绪,由于不是很熟悉...

Spring3 MVC中使用Swagger生成API文档

swagger集成springMVC框架,自动生成接口文档与测试框架。
  • jia20003
  • jia20003
  • 2016年02月19日 23:16
  • 38717

swagger整合spring mvc教程

前文:          在日常工作中,开发人员经常会遇到写接口文档的工作,一般都是word文档,带来书写麻烦、维护麻烦的问题,比如改了源代码忘了更新文档、解释不明确带来歧义、无法在线尝试等等。...

springmvc集成swagger实现接口文档自动化生成

一直苦于文档整理工作,因为这是一个很无聊的工作,偶然在网上看到了swagger这东西,感觉不错,于是动手集成了一下,眼前一亮           Swagger 是一个规范和完整的框架,用于生成、描述...

SpringMVC+Swagger UI生成可视图的API文档(详细图解)

SpringMVC+Swagger生成文档详细图解,以及遇到的异常处理

基于swagger的RESTful API

基于swagger的RESTful API摘要: 前言 RESTful架构,是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便,所以正得到越来越多网站的采用。后端通过提供一套标...
  • Derekwh
  • Derekwh
  • 2016年07月01日 16:59
  • 6017

swagger-maven-plugin自动生成swagger.json(springmvc项目)

1,加入依赖: io.swagger swagger-core 1.5.16 2,加入插件 com.github.kongchen ...

swagger-ui教程-构建api接口文档工具

swagger-ui教程-构建api接口文档工具
  • wyqlxy
  • wyqlxy
  • 2015年11月04日 10:53
  • 7458
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:使用swagger生成API的json文件
举报原因:
原因补充:

(最多只允许输入30个字)