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用。


目录
相关文章
|
13天前
|
JSON Kubernetes API
kubernetes REST Api详解(导入Swagger至Postman)
kubernetes REST Api详解(导入Swagger至Postman)
26 1
|
26天前
|
Java API Maven
淘东电商项目(05) - Swagger及网关统一管理API
淘东电商项目(05) - Swagger及网关统一管理API
32 0
|
27天前
|
Java API Maven
微服务技术系列教程(27) - SpringCloud- Zuul整合Swagger管理微服务所有API
微服务技术系列教程(27) - SpringCloud- Zuul整合Swagger管理微服务所有API
24 0
|
2月前
|
安全 Java API
解决 Swagger API 未授权访问漏洞:完善分析与解决方案
Swagger 是一个用于设计、构建、文档化和使用 RESTful 风格的 Web 服务的开源软件框架。它通过提供一个交互式文档页面,让开发者可以更方便地查看和测试 API 接口。然而,在一些情况下,未经授权的访问可能会导致安全漏洞。本文将介绍如何解决 Swagger API 未授权访问漏洞问题。
|
2月前
|
JSON 数据可视化 安全
Swagger 管理 API 的一些经验分享
Swagger 管理 API 的一些经验分享
36 0
|
4月前
|
开发框架 .NET 中间件
Swagger的 ASP.NET Core Web API 帮助页
使用 Web API 时,了解其各种方法对开发人员来说可能是一项挑战。 Swagger 也称为OpenAPI,解决了为 Web API 生成有用文档和帮助页的问题。 它具有诸如交互式文档、客户端 SDK 生成和 API 可发现性等优点。
41 0
|
4月前
|
Java 测试技术 API
Spring Boot之Restful服务与Swagger框架:构建易用的API文档与测试工具
本篇详细介绍了如何在Spring Boot应用中构建Restful服务,并结合Swagger框架实现自动生成API文档和提供API测试工具的方法。通过编写Controller类定义Restful API,以及配置Swagger框架,读者可以轻松地生成API文档和进行API测试,从而提升开发效率和项目可维护性。该博文帮助读者了解了如何使用Spring Boot和Swagger框架来简化API文档编写和测试的过程,为Web应用开发提供了有力的支持。
160 2
Spring Boot之Restful服务与Swagger框架:构建易用的API文档与测试工具
|
4月前
|
Java 测试技术 API
探索Swagger:简化API文档管理与测试的利器
在现代的应用开发中,API(Application Programming Interface)是不可或缺的一部分,用于实现不同系统之间的通信和数据交换。然而,对于开发者来说,编写和管理API文档以及进行API测试可能是繁琐的任务。Swagger作为一款强大的API文档生成和测试工具,为我们提供了一种简化的解决方案。本文将深入探讨Swagger的基本概念、特点,以及如何在实际应用中使用它进行API文档管理和测试。
76 1
|
5月前
|
安全 数据可视化 Java
Swagger 自动生成 Api 文档:简化接口文档编写
自动生成 API 文档的好处不言而喻,它可以提供给你的团队或者外部协作者,方便 API 使用者准确地调用到你的 API。为了降低手动编写文档带来的错误,很多 API 开发者会偏向于寻找一些好的方法来自动生成 API 文档。
Swagger 自动生成 Api 文档:简化接口文档编写
热门文章
最新文章
相关产品
云迁移中心
推荐文章
更多