Spring3 MVC中使用Swagger生成API文档

简介: Spring3 MVC中使用Swagger生成API文档

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 />

相关文章
|
9天前
|
数据可视化 Java API
Spring Boot与Swagger的集成
Spring Boot与Swagger的集成
|
9天前
|
Java API 开发者
在Spring Boot中集成Swagger API文档
在Spring Boot中集成Swagger API文档
|
8天前
|
开发框架 Java 测试技术
Spring Boot中的API文档生成
Spring Boot中的API文档生成
|
14天前
|
JSON Java API
Spring Boot中使用OpenAPI生成API文档
Spring Boot中使用OpenAPI生成API文档
|
14天前
|
存储 API Go
学习gin-vue-admin之创建api和swagger
学习gin-vue-admin之创建api和swagger
|
19天前
|
Java API Spring
Spring Boot中配置Swagger用于API文档
Spring Boot中配置Swagger用于API文档
|
Java API
Java:一个API文档框架Swagger
Java:一个API文档框架Swagger
108 0
Java:一个API文档框架Swagger
|
13天前
|
NoSQL 安全 API
如何有效提升 API 接口的安全性?
**API安全关键在于验证和防刷。通过排序参数、生成签名和MD5加密确保请求合法性。使用Redis限制请求频率,防止接口被恶意刷取。验证和防刷策略结合,保护API免受攻击和滥用。**
33 0
|
18天前
|
JSON 安全 API
如何高效编写API接口:以Python与Flask为例
构建RESTful API的简明教程:使用Python的Flask框架,从环境准备(安装Python,设置虚拟环境,安装Flask)到编写首个API(包括获取用户列表和单个用户信息的路由)。运行API服务器并测试在`http://127.0.0.1:5000/users`。进阶话题包括安全、数据库集成、API文档生成和性能优化。【6月更文挑战第27天】
42 7
|
15天前
|
Java API PHP
【亲测有效,官方提供】php版本企查查api接口请求示例代码,php请求企查查api接口,thinkphp请求企查查api接口
【亲测有效,官方提供】php版本企查查api接口请求示例代码,php请求企查查api接口,thinkphp请求企查查api接口
22 1