Swagger环境搭建

一、概述

 swagger简述

Swagger API框架,用于管理项目中API接口,属当前最流行的API接口管理工具。 Swagger是一个开源框架(Web框架),功能强大,UI界面漂亮,支持在线测试!
Swagger的目标是对REST API定义一个标准的和语言无关的接口,可让人和计算机无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过Swagger进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger消除了调用服务时可能会有的猜测。

Swagger是一组开源项目,主要项目如下:

Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。
Swagger-js: 用于JavaScript的Swagger实现。
Swagger-node-express: Swagger模块,用于node.js的Express web应用框架。
Swagger-ui:一个无依赖的HTML、JS和CSS集合,可以为Swagger兼容API动态生成优雅文档。
Swagger-codegen:一个模板驱动引擎,通过分析用户Swagger资源声明以各种语言生成客户端代码。
Swagger-editor:可让使用者在浏览器里以YAML格式编辑Swagger API规范并实时预览文档。可以生成有效的Swagger JSON描述,并用于所有Swagger工具(代码生成、文档等等)中。

我们需要的:
1、Swagger可视化界面
Swagger-ui: 从https://github.com/swagger-api/swagger-ui 获取3.0版本以下,2.0版本以上。
其所有的 dist 目录下东西放到需要集成的项目里,
2、相关jar包
classmate-1.1.0.jar:
guava-15.0.jar:Guava工程包含了若干被Google的 Java项目广泛依赖 的核心库,例如:集合 [collections] 、缓存 [caching] 、原生类型支持 [primitives support] 、并发库 [concurrency libraries] 、通用注解 [common annotations] 、字符串处理 [string processing] 、I/O 等等。
guava类似Apache Commons工具集
jackson-annotations-2.0.4.jar:
jackson-core-2.1.1.jar:
jackson-databind-2.1.1.jar:
jackson-jaxrs-json-provider-2.0.0.jar:
jackson-module-jaxb-annotations-2.0.0.jar:
jackson-module-scala-2.0.0.jar:
swagger-annotations-1.3.11.jar:
swagger-models-1.0.2.jar:
swagger-springmvc-1.0.2.jar:

3、Maven依赖

<dependency>
       <groupId>com.mangofactory</groupId>
       <artifactId>swagger-springmvc</artifactId>
        <version>1.0.2</version>
    </dependency>
    <dependency>
       <groupId>com.mangofactory</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.0.2</version>
    </dependency>
    <dependency>
       <groupId>com.wordnik</groupId>
       <artifactId>swagger-annotations</artifactId>
        <version>1.3.11</version>
    </dependency>
    <dependency>
       <groupId>com.google.guava</groupId>
       <artifactId>guava</artifactId>
        <version>15.0</version>
    </dependency>
    <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-annotations</artifactId>
        <version>2.0.4</version>
    </dependency>
    <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-databind</artifactId>
        <version>2.1.1</version>
    </dependency>
    <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-core</artifactId>
        <version>2.1.1</version>
    </dependency>
    <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-jaxrs-json-provider</artifactId>
        <version>2.0.0</version>
    </dependency>
    <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-module-jaxb-annotations</artifactId>
        <version>2.0.0</version>
    </dependency>
    <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-module-scala</artifactId>
        <version>2.0.0</version>
    </dependency>
    <dependency>
       <groupId>com.fasterxml</groupId>
        <artifactId>classmate</artifactId>
        <version>1.1.0</version>
    </dependency>

二、使用方法
Step 1:
解压swagger-ui,将dist文件夹下的所有文件copy到自己的项目中,本文放入 src/main/webapp/swagger/ 目录下。

修改swagger/index.html文件,默认是从连接http://petstore.swagger.io/v2/swagger.json获取 API 的 JSON,这里需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式,{}中的值根据自身情况填写。比如我的url值为:http://localhost:8088/transaction/api-docs

因为swagger-ui是静态资源,需要将web.xml中对请求的拦截做如下修改

在这里插入图片描述
在这里插入图片描述
Step 2:
创建加载文件 SwaggerConfig.java(名称可以随便起)
在这里插入图片描述
Step 3:
添加配置:在spring-mvc.xml文件里配置如下
在这里插入图片描述
Step 4:
向controller里加入相应注解
在这里插入图片描述
上述代码是Controller中的一个方法,@ApiOperation注解对这个方法进行了说明,@ApiParam注解对方法参数进行了说明。关于这两个注解的使用,可以参看源码。这样子,Swagger就可以扫描接口方法,得到我们自定义的接口说明内容。
说明:
其中@ApiOperation和@ApiParam为添加的API相关注解,个参数说明如下:
@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”;其他参数可参考源码;
@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”)

Step 5:
打开浏览器直接访问swagger目录下的index.html文件,即可看到接口文档说明了。
在这里插入图片描述
常见问题解决办法:
1、如果出现如下错误,在web.xml里加上如下配置:
在这里插入图片描述
在这里插入图片描述

  • 1
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值