Spring3 MVC中使用Swagger生成API文档

简介: Spring3 MVC中使用Swagger生成API文档一:Swagger介绍Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档,同时swagger-ui还可以测试spring restful风格的接口功能。

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 />
目录
相关文章
|
2月前
|
数据采集 人工智能 Java
1天消化完Spring全家桶文档!DevDocs:一键深度解析开发文档,自动发现子URL并建立图谱
DevDocs是一款基于智能爬虫技术的开源工具,支持1-5层深度网站结构解析,能将技术文档处理时间从数周缩短至几小时,并提供Markdown/JSON格式输出与AI工具无缝集成。
134 1
1天消化完Spring全家桶文档!DevDocs:一键深度解析开发文档,自动发现子URL并建立图谱
|
2月前
|
存储 JSON API
如何将 Swagger 文档导出为 PDF 文件
你会发现自己可能需要将 Swagger 文档导出为 PDF 或文件,以便于共享和存档。在这篇博文中,我们将指导你完成将 Swagger 文档导出为 PDF 格式的过程。
|
2月前
|
存储 人工智能 Java
Spring AI与DeepSeek实战四:系统API调用
在AI应用开发中,工具调用是增强大模型能力的核心技术,通过让模型与外部API或工具交互,可实现实时信息检索(如天气查询、新闻获取)、系统操作(如创建任务、发送邮件)等功能;本文结合Spring AI与大模型,演示如何通过Tool Calling实现系统API调用,同时处理多轮对话中的会话记忆。
560 57
|
2月前
|
XML JSON API
如何从 Swagger 导出 API 文档
Swagger 使这项任务相对简单,允许开发者以各种格式(如 JSON 和 YAML)导出 API 文档。在这篇博文中,我们将详细探讨如何从 Swagger 导出 API 文档。
如何从 Swagger 导出 API 文档
|
7月前
|
监控 Java 应用服务中间件
高级java面试---spring.factories文件的解析源码API机制
【11月更文挑战第20天】Spring Boot是一个用于快速构建基于Spring框架的应用程序的开源框架。它通过自动配置、起步依赖和内嵌服务器等特性,极大地简化了Spring应用的开发和部署过程。本文将深入探讨Spring Boot的背景历史、业务场景、功能点以及底层原理,并通过Java代码手写模拟Spring Boot的启动过程,特别是spring.factories文件的解析源码API机制。
204 2
|
8月前
|
Java API 数据库
如何使用Spring Boot构建RESTful API,以在线图书管理系统为例
【10月更文挑战第9天】本文介绍了如何使用Spring Boot构建RESTful API,以在线图书管理系统为例,从项目搭建、实体类定义、数据访问层创建、业务逻辑处理到RESTful API的实现,详细展示了每个步骤。通过Spring Boot的简洁配置和强大功能,开发者可以高效地开发出功能完备、易于维护的Web应用。
242 3
|
8月前
|
IDE Java API
基于Spring Boot REST API设计指南
【10月更文挑战第4天】 在现代的软件开发中,RESTful API已经成为了构建网络应用的标准之一。它通过HTTP协议提供了与资源交互的方式,使得不同的应用程序能够进行数据交互。Spring Boot作为一个功能强大的框架,它简化了配置和开发流程,成为了构建RESTful API的理想选择。本文将详细介绍如何在Spring Boot中设计和实现高质量的RESTful API,并提供一些最佳实践。
153 1
|
8月前
|
缓存 Java API
基于Spring Boot REST API设计指南
【10月更文挑战第11天】 在构建现代Web应用程序时,RESTful API已成为一种标准,使得不同的应用程序能够通过HTTP协议进行通信,实现资源的创建、读取、更新和删除等操作。Spring Boot作为一个功能强大的框架,能够轻松创建RESTful API。本文将详细介绍如何在Spring Boot中设计和实现高质量的RESTful API。
308 61
|
6月前
|
存储 安全 Java
Spring Boot 编写 API 的 10条最佳实践
本文总结了 10 个编写 Spring Boot API 的最佳实践,包括 RESTful API 设计原则、注解使用、依赖注入、异常处理、数据传输对象(DTO)建模、安全措施、版本控制、文档生成、测试策略以及监控和日志记录。每个实践都配有详细的编码示例和解释,帮助开发者像专业人士一样构建高质量的 API。
205 9
|
7月前
|
Java 测试技术 API
详解Swagger:Spring Boot中的API文档生成与测试工具
详解Swagger:Spring Boot中的API文档生成与测试工具
422 4