cpj-swagger

原文地址:https://github.com/3cpj/swagger

1. Swagger是什么?

官方说法:Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

个人觉得,swagger的一个最大的优点是能实时同步api与文档。在项目开发过程中,发生过多次:修改代码但是没有更新文档,前端还是按照老旧的文档进行开发,在联调过程中才发现问题的情况(当然依据开闭原则,对接口的修改是不允许的,但是在项目不稳定阶段,这种情况很难避免)。

cpj-swagger通过与swagger ui一起快速为您的web项目产生接口文档,并且支持在线测试接口。cpj-swagger可以很方便的与struts2spring mvcservlet集成使用,下面的教程将详细说明如何使用cpj-swagger。

目录

一. 加入依赖JAR文件
二. 配置
三. 标注你的接口
四. 访问接口文档
五. 核心API
六. 示例程序下载

一. 加入依赖JAR文件

  • maven:
<dependency>
<groupId>com.github.3cpj</groupId>
<artifactId>cpj-swagger</artifactId>
<version>1.2.1</version>
</dependency>

二. 配置

1. 选择使用方式

您可以通过三种方式来使用cpj-swagger

  • 与strut2集成
    如果您的web项目是基于strut2的,您可以在您的strut2配置文件中加入如下代码来快速集成cpj-swagger
<constant name="struts.enable.DynamicMethodInvocation" value="true" />
<constant name="struts.devMode" value="true" /> <package name="api" namespace="/api" extends="struts-default" >
<action name="*" class="com.cpj.swagger.support.struts2.ApiAction" method="{0}">
</action>
</package>
  • 与spring mvc集成 
    如果您的web项目是基于spring mvc的,您可以在您的spring mvc配置文件中加入如下代码来快速集成cpj-swagger
 <context:component-scan base-package="com.cpj.swagger.support.springmvc">
<context:include-filter type="annotation" expression="org.springframework.stereotype.Controller"/>
</context:component-scan>
  • 与servlet集成
    如果您的web项目是基于servlet的,您可以在您的web.xml配置文件中加入如下代码来快速集成cpj-swagger
<servlet>
<servlet-name>apiServlet</servlet-name>
<servlet-class>com.cpj.swagger.support.servlet.ApiServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>apiServlet</servlet-name>
<url-pattern>/api/*</url-pattern>
</servlet-mapping>

2. 修改配置项

您需要在项目的源文件目录下添加一个swagger.properties文件,并加入以下配置项:

packageToScan=com.cpj.swagger.action
apiDescription=Swagger Demo
apiTitle=Swagger Demo
apiVersion=1.0.0
teamOfService=www.cpj.com
devMode=true

cpj-swagger的配置信息都必须写在swagger.properties文件里面。具体的配置项及其说明如下:

说明
apiFile 扫描生成json文件的存放路径
packageToScan 扫描的包
apiDescription 接口文档描述
apiTitle 接口文档标题
apiVersion 接口版本
teamOfService 服务团队
apiHost 接口主机地址
apiBasePath 接口基路径
devMode 是否启用开发模式,如果开启则每次获取接口文档的时候都会扫描类
suffix 接口请求地址后缀,如.action

三. 标注你的接口

接下来需要用cpj-swagger提供的注解来标明你的接口,下面以spring mvc为例来说明如何标注接口,其他方式请参考示例程序

@Controller
@APIs("/demo")
@RequestMapping("/demo")
public class DemoController {
@API(value="login", summary="示例1", parameters={
@Param(name="username", description="用户名", type="string"),
@Param(name="password", description="密码", type="string", format="password"),
@Param(name="image" , description="图片", type="file", format="binary")
})
@RequestMapping(value="login", method=RequestMethod.POST)
public void login(HttpServletResponse response, String username, String password, MultipartFile image)
throws Exception {
response.setContentType("application/json;charset=utf-8");
JSONWriter writer = new JSONWriter(response.getWriter());
Map<String, String> user = new HashMap<String, String>();
user.put("username", username);
user.put("password", password);
writer.writeObject(user);
writer.flush();
writer.close();
}
}
 

四. 访问接口文档

在完成前面的工作之后,您可以部署好您的web项目,然后在浏览器输入以下地址就可以访问接口文档了:http://127.0.0.1:8080/您的项目名/api/index

五. 核心API

1. 注解 @com.cpj.swagger.annotation.APIs

该注解放在一个类上面,用来表明类中包含作为HTTP接口的方法(被注解@com.cpj.swagger.annotation.API标注了的方法)。 该注解的value用来设置接口的前缀,这和struts2的命名空间很像。使用示例如下:

@APIs("/demo")
public class DemoController { }
 

2. 注解 @com.cpj.swagger.annotation.API

该注解放在一个方法上面,用来表明方法是HTTP接口方法,注解的属性说明如下:

value

与注解@com.cpj.swagger.annotation.APIsvalue属性一起来指定接口的地址,例如有如下设置:

@APIs("/demo")
public class DemoController {
@API(value="login"})
public void login()
}
}
 

那么login方法对应的接口地址为: youhost/demo/login

parameters

用来指定接口的请求参数,详情参见注解Param的说明。

summary

接口功能简述。

description

接口功能详细说明。

method

请求方式,默认是POST。

consumes

允许的请求MIME,比如:multipart/form-data、application/xml、application/json默认是application/json; charset=utf-8。 
特别说明:
当为 multipart/form-data 时,Param 的in属性必须为formData,但是in为path、header时Param不用遵循此规则。

3. 注解 @com.cpj.swagger.annotation.Param

用来说明请求参数,例如:

@API(value="login", summary="示例1", parameters={
@Param(name="username", description="用户名", type="string"),
@Param(name="password", description="密码", type="string", format="password")})
@RequestMapping(value="login", method=RequestMethod.POST)
public void login(HttpServletResponse response, String username, String password) throws Exception {
}
 

这表明该接口需要两个请求参数,及usernamepassword。 注解@com.cpj.swagger.annotation.Param的属性说明如下:

name

参数名

in

输入参数类型,可取如下值:

  • query - 参数拼接到url中
  • body - 参数直接放入请求体中
  • path - restful风格的参数传递
  • header - 参数放在请求头中
  • formData - 参数通过form表单提交

特别说明:

  • 当前请求方式为POST的时候,默认值为formData
  • 请求方式为非POST的时候,默认值为query

type

数据类型, 与format一起指定请求参数的数据类型。 type 和 format 的可选值如下:

通用名 type format 备注
integer integer int32 signed 32 bits
long integer int64 signed 64 bits
float number float  
double number double  
string string    
byte string byte base64 encoded characters
binary string binary any sequence of octets
boolean boolean    
date string date As defined by full-date - RFC3339
dateTime string date-time As defined by date-time - RFC3339
password string password Used to hint UIs the input needs to be obscured.

format

数据格式,type一起指定请求参数的数据类型。

description

参数说明

required

是否是必须参数, 默认是false

六. 示例程序下载

spring mvc 
struts2 
servlet

七. 与struts2 整合项目演示

进入git命令行,输入命令下载代码

git clone https://github.com/3cpj/swagger-demo-struts2.git

然后进入项目文件夹内

cd swagger-demo-struts2/

把项目转成eclipse项目

mvn eclipse:eclipse 

导入eclipse之后发布项目到tomcat,然后启动项目,访问地址:http://localhost:8080/swagger-demo-struts2/api/index

运行效果:

整个接口的参数一目了然。

cpj-swagger分别整合struts2、spring mvc、servlet的更多相关文章

  1. 使用IDEA整合spring4+spring mvc+hibernate

    配置文件 spring-mvc.xml 1 <?xml version="1.0" encoding="UTF-8"?> 2 <beans x ...

  2. 整合struts2+spring+hibernate

     一.准备struts2+spring+hibernate所须要的jar包:        新建web项目并将jar包引入到project项目中. 二.搭建struts2环境        a.在 ...

  3. 重新学习之spring第三个程序,整合struts2+spring

    第一步:导入Struts2jar包+springIOC的jar包和Aop的Jar包 第二步:建立applicationContext.xml文件+struts.xml文件+web.xml文件 web. ...

  4. SSH之IDEA2017整合Struts2+Spring+Hibernate

    转自:https://blog.csdn.net/sysushui/article/details/68937005

  5. 控制层技术:Servlet+reflection、Struts2、Spring MVC三者之间的比较学习

    Servlet Struts2 Spring MVC 处理用户提交的数据 基于MVC设计模式的Web应用程序 是一个框架 是MVC框架 导入servlet包,配置web.xml文件 web.xml & ...

  6. Java框架搭建-Maven、Mybatis、Spring MVC整合搭建

    1. 下载eclipse 到网站下载 http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/marsr 选择 ...

  7. IDEA下创建Maven项目,并整合使用Spring、Spring MVC、Mybatis框架

    项目创建 本项目使用的是IDEA 2016创建. 首先电脑安装Maven,接着打开IDEA新建一个project,选择Maven,选择图中所选项,下一步. 填写好GroupId和ArtifactId, ...

  8. spring、spring mvc、mybatis框架整合基本知识

    学习了一个多月的框架知识了,这两天很想将它整合一下.网上看了很多整合案例,基本都是基于Eclipse的,但现在外面公司基本都在用Intellij IDEA了,所以结合所学知识,自己做了个总结,有不足之 ...

  9. Spring + Spring MVC + MyBatis 整合

    1.所需要Jar包 ? <!-- Spring3.0.1包 -->   org.springframework.web-3.0.1 系列   <!-- 公共包 -->   sl ...

  10. 【Java】Spring MVC 扩展和SSM框架整合

    开发web项目通常很多地方需要使用ajax请求来完成相应的功能,比如表单交互或者是复杂的UI设计中数据的传递等等.对于返回结果,我们一般使用JSON对象来表示,那么Spring MVC中如何处理JSO ...

随机推荐

  1. nodejs的http-server--web前端福利

    很多web前端在日常开发的时候可能会想常开发是谁. 不好意思,说错了. 很多web前端在日常开发的时候总是避免不了让所写页面在服务器环境下执行. 比如当你在用angularjs的route模块等等等. ...

  2. 详解 JavaScript 中 splice() 方法

    splice() 方法是一个比较少用的方法,但是功能确实很好,并且在我们 coding 的时候,经常有需要 splice() 方法,先介绍一下该方法. 在 JavaScript 中 splice() ...

  3. 图解HTTP总结(1)——了解Web及网络基础

    Web页面不能凭空显示出来.根据Web浏览器地址栏指定的URL,Web浏览器从Web服务器端获取文件资源等信息,从而显示出Web页面. Web使用一种名为HTTP(HyperText  Transfe ...

  4. JDK学习---深入理解Comparator、TreeSet、TreeMap为什么可以排序

    我本来打算仔细的去分析分析TreeSet和TreeMap排序规则,并且从底层实现和数据结构入手.当我去读完底层源码以后,我感觉我就的目标定的太大了,单单就是数据结构就够我自己写很久了,因此我决定先易后 ...

  5. graphviz使用

    官方网站:http://www.graphviz.org/ Graphviz (Graph Visualization Software) 是一个由AT&T实验室启动的开源工具包.DOT是一种 ...

  6. [Bzoj1037][ZJOI2008]生日聚会(DP)

    Description 题目链接 Solution 这题状态比较难想, \(dp[i][j][g][h]\)表示强i个人有j个男生,在某个区间男生最多比女生多g人,女生最多比男生多h人的方案数,然后D ...

  7. [Noip2016]组合数(数论)

    题目描述 组合数表示的是从n个物品中选出m个物品的方案数.举个例子,从(1,2,3) 三个物品中选择两个物品可以有(1,2),(1,3),(2,3)这三种选择方法.根据组合数的定 义,我们可以给出计算 ...

  8. ASP.NET 使用 MySQL

    基本是通用的 C#与MySQL的交互, 先添加MySQL.Data.dll(位于MySQL安装目录下的Connector NET 8.0\Assemblies${version}目录下)引用, 之后代 ...

  9. 深度学习 GPU环境 Ubuntu 16.04 + Nvidia GTX 1080 + Python 3.6 + CUDA 9.0 + cuDNN 7.1 + TensorFlow 1.6 环境配置

    本节详细说明一下深度学习环境配置,Ubuntu 16.04 + Nvidia GTX 1080 + Python 3.6 + CUDA 9.0 + cuDNN 7.1 + TensorFlow 1.6 ...

  10. Java 多线程并发编程一览笔录

    Java 多线程并发编程一览笔录 知识体系图: 1.线程是什么? 线程是进程中独立运行的子任务. 2.创建线程的方式 方式一:将类声明为 Thread 的子类.该子类应重写 Thread 类的 run ...