swagger (可视化RESTful API的工具)

简介: swagger 是一个可视化RESTful WebService的工具。 官网:http://swagger.io 效果 下图可以看出,swagger清晰地展现了web服务的方法、地址、发送json格式与应答json格式。还可以通过它直接进行服务调用,查看结果。 图1 swagger的效果 工作原理 视图部分: swagger-ui是一系列css\js资源,它通过html页

swagger 是一个可视化RESTful WebService的工具。

官网:http://swagger.io

效果

下图可以看出,swagger清晰地展现了web服务的方法、地址、发送json格式与应答json格式。还可以通过它直接进行服务调用,查看结果。


图1 swagger的效果

工作原理

视图部分: swagger-ui是一系列css\js资源,它通过html页面向用户展示一个应用的RESTful API信息。它通过向swagger-core后台模块发送ajax请求获取必要的信息。

其实就是一个json,我们可以截取一点来看看:

//swagger.json 示例
{
	"swagger": "2.0",
	"info": {
		"version": "1.0.0",
		"title": ""
	},
	"host": "localhost:8080",
	"basePath": "/webService",
	"tags": [{
		"name": "hello"
	}],
	"schemes": ["http"],
	"paths": {
		"/helloworld": {
			"get": {
				"tags": ["hello"],
				"operationId": "wsHello",
				"parameters": [],
				"responses": {
					"200": {
						"description": "successful operation",
						"schema": {
							"type": "string"
						},
						"headers": {
							
						}
					}
				}
			}
		}
	}
}


后台部分:swagger-core通过 io.swagger.annotations.Api等注解感知到我们的API信息,从而以json格式应答web页面的ajax请求。

服务器部分:可以在tomcat中用。


与jersey集成部署

jersey在tomcat中的配置太灵活了,可以写在web.xml中作servlet,也可以作filter,还可以在java代码中继承某个类,更可以继承相关的其他类!以下是我试验成功的一种情况。
1.Adding the dependencies to your application
<dependency>
	<groupId>io.swagger</groupId>
	<artifactId>swagger-jersey2-jaxrs</artifactId>
	<version>1.5.0</version>
</dependency>

2 .Hooking up Swagger-Core in your Application
即让jersey感知到swagger的存在。
public class App extends ResourceConfig {
	public App() {
		// 向jersey框架注册资源类,凡完全限定名是以指定字符串开头的类,都将包含
		packages("com.likeyichu.webservice.resource");
		register(JacksonFeature.class);
		//swagger
		Set<Class<?>> resources = new HashSet<>();
	    resources.add(io.swagger.jaxrs.listing.ApiListingResource.class);
        resources.add(io.swagger.jaxrs.listing.SwaggerSerializers.class);
		registerClasses(resources);
	}
}

3 .Configure and Initialize Swagger

添加servlet即可,主要是为了配置我们api的地址,因为swagger可以发送请求的。

  <servlet>
        <servlet-name>Jersey2Config</servlet-name>
        <servlet-class>io.swagger.jersey.config.JerseyJaxrsConfig</servlet-class>
        <init-param>
            <param-name>api.version</param-name>
            <param-value>1.0.0</param-value>
        </init-param>
        <init-param>
            <param-name>swagger.api.basepath</param-name>
            <param-value>http://localhost:8080/webService/api</param-value>
        </init-param>
        <load-on-startup>2</load-on-startup>
    </servlet>

配置完成,即可在浏览器地址栏中输入webservice目录\swagger.json进行验证。

4.前端资源

github上的swaggerUI项目就是,下载下来就好。注意要改index.html,里面swagger.json的地址指向自己的就好。

常见异常

微笑现象:无穷递归早成栈溢出。
代码:
@Api(value="swagger test")
@Path("book")
@JsonAutoDetect
@JsonPropertyOrder(value = {"price", "name"})
@JsonIgnoreProperties(value = {"year"})
public class Book {
	@JsonProperty("name1")
	public String name = "Physics";
	public String price = "123";
	public String year = "2015";
	@GET
	@Produces(MediaType.APPLICATION_JSON)
	public Book wsBook(){
		return new Book();
	}
}

微笑原因:swagger在进行资源扫描的时候有以下步骤:
1.因为@Api注解找到了Book类;
2.发现了类下的wsBook()这个函数,它的返回值是Book对象,于是查看它的类有没有@Api注解。发现有,转入步骤1。
于是就造成了无穷递归。
解决办法是资源类不当做Pojo用。


目录
相关文章
|
21天前
|
人工智能 数据可视化 API
开箱即用的可视化AI应用编排工具 Langflow,可调用魔搭免费API作为tool
ModelScope 社区基于优秀的开源可视化AI应用编排工具 Langflow 搭建了创空间,以方便社区开发者基于社区开源模型及免费魔搭 API-Inference,快速创建Agent应用、RAG应用并将其部署为API服务。
176 14
|
1月前
|
XML JSON API
Understanding RESTful API and Web Services: Key Differences and Use Cases
在现代软件开发中,RESTful API和Web服务均用于实现系统间通信,但各有特点。RESTful API遵循REST原则,主要使用HTTP/HTTPS协议,数据格式多为JSON或XML,适用于无状态通信;而Web服务包括SOAP和REST,常用于基于网络的API,采用标准化方法如WSDL或OpenAPI。理解两者区别有助于选择适合应用需求的解决方案,构建高效、可扩展的应用程序。
|
1月前
|
机器学习/深度学习 设计模式 API
Python 高级编程与实战:构建 RESTful API
本文深入探讨了使用 Python 构建 RESTful API 的方法,涵盖 Flask、Django REST Framework 和 FastAPI 三个主流框架。通过实战项目示例,详细讲解了如何处理 GET、POST 请求,并返回相应数据。学习这些技术将帮助你掌握构建高效、可靠的 Web API。
|
5月前
|
JSON 缓存 JavaScript
深入浅出:使用Node.js构建RESTful API
在这个数字时代,API已成为软件开发的基石之一。本文旨在引导初学者通过Node.js和Express框架快速搭建一个功能完备的RESTful API。我们将从零开始,逐步深入,不仅涉及代码编写,还包括设计原则、最佳实践及调试技巧。无论你是初探后端开发,还是希望扩展你的技术栈,这篇文章都将是你的理想指南。
|
4月前
|
JSON JavaScript 前端开发
深入浅出Node.js:从零开始构建RESTful API
在数字化时代的浪潮中,后端开发作为连接用户与数据的桥梁,扮演着至关重要的角色。本文将引导您步入Node.js的奇妙世界,通过实践操作,掌握如何使用这一强大的JavaScript运行时环境构建高效、可扩展的RESTful API。我们将一同探索Express框架的使用,学习如何设计API端点,处理数据请求,并实现身份验证机制,最终部署我们的成果到云服务器上。无论您是初学者还是有一定基础的开发者,这篇文章都将为您打开一扇通往后端开发深层知识的大门。
101 12
|
5月前
|
XML JSON 缓存
深入理解RESTful API设计原则与实践
在现代软件开发中,构建高效、可扩展的应用程序接口(API)是至关重要的。本文旨在探讨RESTful API的核心设计理念,包括其基于HTTP协议的特性,以及如何在实际应用中遵循这些原则来优化API设计。我们将通过具体示例和最佳实践,展示如何创建易于理解、维护且性能优良的RESTful服务,从而提升前后端分离架构下的开发效率和用户体验。
|
5月前
|
监控 安全 API
深入浅出:构建高效RESTful API的最佳实践
在数字化时代,API已成为连接不同软件和服务的桥梁。本文将带你深入了解如何设计和维护一个高效、可扩展且安全的RESTful API。我们将从基础概念出发,逐步深入到高级技巧,让你能够掌握创建优质API的关键要素。无论你是初学者还是有经验的开发者,这篇文章都将为你提供实用的指导和启示。让我们一起探索API设计的奥秘,打造出色的后端服务吧!
|
5月前
|
JSON 缓存 测试技术
构建高效RESTful API的后端实践指南####
本文将深入探讨如何设计并实现一个高效、可扩展且易于维护的RESTful API。不同于传统的摘要概述,本节将直接以行动指南的形式,列出构建RESTful API时必须遵循的核心原则与最佳实践,旨在为开发者提供一套直接可行的实施框架,快速提升API设计与开发能力。 ####
|
5月前
|
JavaScript NoSQL API
深入浅出Node.js:从零开始构建RESTful API
在数字化时代的浪潮中,后端开发如同一座灯塔,指引着数据的海洋。本文将带你航行在Node.js的海域,探索如何从一张白纸到完成一个功能完备的RESTful API。我们将一起学习如何搭建开发环境、设计API结构、处理数据请求与响应,以及实现数据库交互。准备好了吗?启航吧!
|
5月前
|
JSON API 数据格式
探索后端开发:从零构建简易RESTful API
在数字时代的浪潮中,后端开发如同搭建一座桥梁,连接着用户界面与数据世界。本文将引导读者步入后端开发的殿堂,通过构建一个简易的RESTful API,揭示其背后的逻辑与魅力。我们将从基础概念出发,逐步深入到实际操作,不仅分享代码示例,更探讨如何思考和解决问题,让每一位读者都能在后端开发的道路上迈出坚实的一步。

热门文章

最新文章