关闭

Spring3 MVC中使用Swagger生成API文档

标签: springspring mvcswagger api
40672人阅读 评论(10) 收藏 举报
分类:

Spring3 MVC中使用Swagger生成API文档

一:Swagger介绍

Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目

实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档,

同时swagger-ui还可以测试spring restful风格的接口功能。其官方网站为:

http://swagger.io/

二:Swagger集成Spring3 MVC步骤

Swagger集成springMVC步骤大致只有如下几步:

1.在pom.xml文件中添加swagger相关的依赖

                <!-- swagger API document -->
		<dependency>
			<groupId>com.mangofactory</groupId>
			<artifactId>swagger-springmvc</artifactId>
			<version>0.6.5</version>
		</dependency>

2.创建classpath路径下创建一个swagger.properties, 添加如下内容:

documentation.services.version=1.0

documentation.services.basePath=http://localhost:8080/yourcontextpath

3.在springMVC的main-servlet.xml文件添加如下配置

	<context:property-placeholder location="classpath:swagger.properties" />
	<bean id="documentationConfig" class="com.mangofactory.swagger.configuration.DocumentationConfig" />

4.重新打包部署你的项目到WEB服务器,访问地址

http://localhost:8080/your-contextpath /api-docs即可看到注解生成的API说明

三:常见swagger注解一览与使用

APIs.@Api

@ApiClass

@ApiError

@ApiErrors

@ApiOperation

@ApiParam

@ApiParamImplicit

@ApiParamsImplicit

@ApiProperty

@ApiResponse

@ApiResponses

@ApiModel

在代码中使用例子:

import java.util.HashMap;
import java.util.Map;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;

import com.wordnik.swagger.annotations.ApiOperation;

@Controller
@RequestMapping("/api/swagger")
public class SwaggerDemoController {
	private static final Logger logger = LoggerFactory.getLogger(SwaggerDemoController.class);
	
	@ApiOperation(value = "query api basic information")
	@RequestMapping(value = "/info", method = RequestMethod.GET)
	@ResponseBody
	public Map<String, String> queryAPIInfo() {
		logger.info("查询更新新版本号");
		Map<String, String> map = new HashMap<String, String>();
		map.put("language", "Java");
		map.put("format", "JSON");
		map.put("tools", "swagger");
		map.put("version", "1.0");
		return map;
	}
	
	@ApiOperation(value = "query data with parameters")
	@RequestMapping(value = "/data", method = RequestMethod.GET)
	@ResponseBody
	public Map<String, String> queryData(@RequestParam String words) {
		logger.info("查询更新新版本号");
		Map<String, String> map = new HashMap<String, String>();
		map.put("keyword", words);
		map.put("data", "this is demo data");
		return map;
	}
}

四:运行swagger-ui测试接口

下载swagger-ui的最新版本到本地,改名为swagger-ui,把dist下面的部署到tomcat

或者任何WEB服务器上,启动后访问如下地址: http://localhost:8080/swagger-ui

注意把swagger-ui中的index.html中的http://petstore.swagger.io/v2/swagger.json改为

http://localhost:8080/your-contextpath /api-docs保存,然后在启动WEB服务器,

显示如下:

展开输入参数以后,点击【try it out】即可测试接口,查看返回数据。
注意:加上之后启动报Bean not found mapping之类的错误,请在对应

xml文件中加上如下的配置:

<context:annotation-config />
<mvc:default-servlet-handler />

3
75
查看评论

swagger注释API详细说明

API详细说明 注释汇总 作用范围 API 使用位置 对象属性 @ApiModelProperty 用在出入参数对象的字段上 协议集描述 @Api 用于controller类上 协议描述 @ApiOperation 用在cont...
  • xupeng874395012
  • xupeng874395012
  • 2017-05-23 10:12
  • 23662

Swagger与RestFul 集成 以及 注解使用Demo

准备工作: 1 按文档搭建Spring Boot 和 Swagger: http://www.cnblogs.com/xiaohanghang/p/6018654.html 另附标准RestFul API规范: www.cnblogs.com/xiaohanghang/p/6018654.html...
  • jun55xiu
  • jun55xiu
  • 2017-04-21 15:45
  • 11259

Swagger简介

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码,了解更多内容,见参考资料。
  • wangnan9279
  • wangnan9279
  • 2015-03-22 21:09
  • 172478

修改接口注解用于swagger接口调用

1、为了能够使用Swagger完成登录验证并调用后台接口,所有的接口都添加如下注解: @ApiOperation("=====接口描述=====") @ApiImplicitParams({     @ApiImplicitPara...
  • u012108512
  • u012108512
  • 2018-02-01 15:07
  • 47

swagger注释API详细说明

API详细说明注释汇总作用范围API使用位置对象属性@ApiModelProperty用在出入参数对象的字段上协议集描述@Api用于controller类上协议描述@ApiOperation用在controller的方法上Response集@ApiResponses用在controller的方法上R...
  • u011402896
  • u011402896
  • 2018-02-05 09:24
  • 49

springfox集成教程

swagger用于定义API文档。 1. 好处: 前后端分离开发API文档非常明确测试的时候不需要再使用URL输入浏览器的方式来访问Controller传统的输入URL的测试方式对于post请求的传参比较麻烦(当然,可以使用postman这样的浏览器插件)springfox基于swagger2,...
  • cws1214
  • cws1214
  • 2016-07-20 16:08
  • 4417

【SpringFox / Swagger文档生成工具】使用过程中的几个问题积累

转载本文请标明出处,谢谢!SpringFox是最新版的Swagger文档生成工具,SpringFox官方文档参见:SpringFox官方参考文档SpringFox与Spring Boot的集成 添加配置类 package focuson.config;import com.dianrong.labe...
  • Hero06206
  • Hero06206
  • 2016-09-26 11:10
  • 7091

Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api

有图有真相,有源代码有真相,有下载地址有真相!!! Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目 实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档, 同时swagger-ui还可以测试spr...
  • FansUnion
  • FansUnion
  • 2016-07-16 12:27
  • 45027

使用apidoc 生成Restful web Api文档

在项目开发过程中,总会牵扯到接口文档的设计与编写,之前使用的都是office工具,写一个文档,总也是不够漂亮和直观。好在git上的开源大神提供了生成文档的工具,so来介绍一下! 该工具是Nodejs的模块,请务必在使用前安装好nodejs环境! 工具名称:apiDoc Git地址:http...
  • soslinken
  • soslinken
  • 2016-01-06 17:29
  • 27179

apidoc的介绍和使用

apidoc是使用编写接口文档非常方便的,一种编写
  • lvbaolin123
  • lvbaolin123
  • 2016-09-26 16:50
  • 6912
    个人说明
    独立图像处理开发者
    图像处理与对象识别算法外包
    OCR与美化类滤镜开发
    安卓与IOS图像类应用开发

    OpenCV学习群:376281510

    学习图像处理技术关注
    公众号:【OpenCV学堂】
    个人联系方式:
    QQ: 57558865
    个人资料
    • 访问:2853807次
    • 积分:24120
    • 等级:
    • 排名:第331名
    • 原创:257篇
    • 转载:1篇
    • 译文:2篇
    • 评论:1398条
    博客专栏
    最新评论