Spring MVC+FastJson+Swagger集成的完整实例教程

基础部分

1. fastjson 简介

fastjson是一个java库,可用于将java对象转换为json表示。它也可以被用来将一个json字符串转换成一个等效的java对象。在转换速度上应该是最快的，几乎成为了项目的标配（在ajax请求和接口开发时一般都会用fastjson而不再使用jackson）。

github：  （）

特性：

• 在服务器端和android客户端提供最佳性能
• 提供简单tojsonstring()和parseobject()方法的java对象转换为json,反之亦然
• 允许存在的无法改变的对象转换为从json
• java泛型的广泛支持
• 允许自定义表示对象
• 支持任意复杂的对象(深继承层次结构和广泛使用泛型类型)

主要特点：

• 快速fast (比其它任何基于java的解析器和生成器更快，包括jackson）
• 强大（支持普通jdk类包括任意java bean class、collection、map、date或enum）
• 零依赖（没有依赖其它任何类库除了jdk）
• 支持注解

2. fastjson api

fastjson api入口类是com.alibaba.fastjson.json，常用的序列化操作都可以在json类上的静态方法直接完成。

// 把json文本parse为jsonobject或者jsonarray 
public static final object parse(string text); 

// 把json文本parse成jsonobject 
public static final jsonobject parseobject(string text)； 

// 把json文本parse为javabean 
public static final <t> t parseobject(string text, class<t> clazz); 

// 把json文本parse成jsonarray 
public static final jsonarray parsearray(string text); 

// 把json文本parse成javabean集合 
public static final <t> list<t> parsearray(string text, class<t> clazz); 

// 将javabean序列化为json文本 
public static final string tojsonstring(object object); 

// 将javabean序列化为带格式的json文本 
public static final string tojsonstring(object object, boolean prettyformat); 

// 将javabean转换为jsonobject或者jsonarray
public static final object tojson(object javaobject); 

jsonarray：相当于list<object>

jsonobject：相当于map<string, object>

serializeconfig: 是对序列化过程中一些序列化过程的特殊配置, 如对一些字段进行格式处理（日期、枚举等）

serializewriter：相当于stringbuffer

serializerfeature属性 ：

• quotefieldnames 输出key时是否使用双引号,默认为true
• usesinglequotes 使用单引号而不是双引号,默认为false
• writemapnullvalue 是否输出值为null的字段,默认为false
• writeenumusingtostring enum输出name()或者original,默认为false
• useiso8601dateformat date使用iso8601格式输出，默认为false
• writenulllistasempty list字段如果为null,输出为[],而非null
• writenullstringasempty 字符类型字段如果为null,输出为”“,而非null
• writenullnumberaszero 数值字段如果为null,输出为0,而非null
• writenullbooleanasfalse boolean字段如果为null,输出为false,而非null
• skiptransientfield 如果是true，类中的get方法对应的field是transient，序列化时将会被忽略。默认为true
• sortfield 按字段名称排序后输出。默认为false
• writetabasspecial 把\t做转义输出，默认为false 不推荐
• prettyformat 结果是否格式化,默认为false
• writeclassname 序列化时写入类型信息，默认为false。反序列化是需用到
• disablecircularreferencedetect 消除对同一对象循环引用的问题，默认为false
• writeslashasspecial 对斜杠'/'进行转义
• browsercompatible 将中文都会序列化为\uxxxx格式，字节数会多一些，但是能兼容ie 6，默认为false
• writedateusedateformat 全局修改日期格式,默认为false。json.deffault_date_format = “yyyy-mm-dd”;json.tojsonstring(obj, serializerfeature.writedateusedateformat);
• disablecheckspecialchar 一个对象的字符串属性中如果有特殊字符如双引号，将会在转成json时带有反斜杠转移符。如果不需要转义，可以使用这个属性。默认为false
• notwriterootclassname 含义
• beantoarray 将对象转为array输出
• writenonstringkeyasstring
• notwritedefaultvalue
• browsersecure
• ignorenonfieldgetter
• writeenumusingname

实战部分

1、pom.xml 中引入spring mvc、 fastjson 依赖

<project xmlns="http://maven.apache.org/pom/4.0.0" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"
 xsi:schemalocation="http://maven.apache.org/pom/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
 <modelversion>4.0.0</modelversion>
 <groupid>com.mengdee</groupid>
 <artifactid>platform-springmvc-webapp</artifactid>
 <packaging>war</packaging>
 <version>0.0.1-snapshot</version>
 <name>platform-springmvc-webapp maven webapp</name>
 <url>http://maven.apache.org</url>

 <properties>
 <project.build.sourceencoding>utf-8</project.build.sourceencoding>
 <junit.version>3.8.1</junit.version>
 <log4j.version>2.5</log4j.version>
 <jstl.version>1.2</jstl.version>
 <spring.version>4.2.3.release</spring.version>
 <fastjson.version>1.2.32</fastjson.version>

 </properties>

 <dependencies>
 <dependency>
 <groupid>junit</groupid>
 <artifactid>junit</artifactid>
 <version>3.8.1</version>
 <scope>test</scope>
 </dependency>

 <dependency>
 <groupid>javax.servlet</groupid>
 <artifactid>jstl</artifactid>
 <version>${jstl.version}</version>
 </dependency>

 <!-- springframework -->
 <dependency>
 <groupid>org.springframework</groupid>
 <artifactid>spring-webmvc</artifactid>
 <version>${spring.version}</version>
 </dependency>
 <dependency>
 <groupid>org.springframework</groupid>
 <artifactid>spring-core</artifactid>
 <version>${spring.version}</version>
 </dependency>
 <dependency>
 <groupid>org.springframework</groupid>
 <artifactid>spring-context</artifactid>
 <version>${spring.version}</version>
 </dependency>
 <dependency>
 <groupid>org.springframework</groupid>
 <artifactid>spring-context-support</artifactid>
 <version>${spring.version}</version>
 </dependency>
 <dependency>
 <groupid>org.springframework</groupid>
 <artifactid>spring-jdbc</artifactid>
 <version>${spring.version}</version>
 </dependency>

 <dependency>
 <groupid>com.alibaba</groupid>
 <artifactid>fastjson</artifactid>
 <version>${fastjson.version}</version>
 </dependency>

 </dependencies>

 <!-- 使用aliyun镜像 -->
 <repositories>
 <repository>
 <id>aliyun</id>
 <name>aliyun</name>
 <url>http://maven.aliyun.com/nexus/content/groups/public</url>
 </repository>
 </repositories>

 <build>
 <finalname>platform-springmvc-webapp</finalname>
 </build>
</project>

2、 配置web.xml

<!doctype web-app public
 "-//sun microsystems, inc.//dtd web application 2.3//en"
 "http://java.sun.com/dtd/web-app_2_3.dtd" >

<web-app>
 <display-name>archetype created web application</display-name>
 <context-param>
 <param-name>contextconfiglocation</param-name>
 <param-value>classpath:conf/spring/spring-*.xml</param-value>
 </context-param>

 <listener>
 <description>spring监听器</description>
 <listener-class>org.springframework.web.context.contextloaderlistener</listener-class>
 </listener>

 <servlet>
 <servlet-name>spring-mvc</servlet-name>
 <servlet-class>org.springframework.web.servlet.dispatcherservlet</servlet-class>
 <init-param> 
 <param-name>contextconfiglocation</param-name> 
 <param-value>/web-inf/spring-servlet.xml</param-value> 
 </init-param>
 <load-on-startup>1</load-on-startup>
 </servlet>
 <servlet-mapping>
 <servlet-name>spring-mvc</servlet-name>
 <url-pattern>/</url-pattern>
 </servlet-mapping>

 <filter>
 <filter-name>characterencodingfilter</filter-name>
 <filter-class>org.springframework.web.filter.characterencodingfilter</filter-class>
 <init-param>
 <param-name>encoding</param-name>
 <param-value>utf-8</param-value>
 </init-param>
 <init-param>
 <param-name>forceencoding</param-name>
 <param-value>true</param-value>
 </init-param>
 </filter>
 <filter-mapping>
 <filter-name>characterencodingfilter</filter-name>
 <url-pattern>/*</url-pattern>
 </filter-mapping>


 <welcome-file-list>
 <welcome-file>/index.jsp</welcome-file>
 </welcome-file-list>

 <error-page>
 <error-code>404</error-code>
 <location>/index.jsp</location>
 </error-page>
</web-app>

3、 配置spring-servlet.xml

<?xml version="1.0" encoding="utf-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"
 xmlns:p="http://www.springframework.org/schema/p"
 xmlns:context="http://www.springframework.org/schema/context"
 xmlns:mvc="http://www.springframework.org/schema/mvc"
 xsi:schemalocation="http://www.springframework.org/schema/beans 
 http://www.springframework.org/schema/beans/spring-beans-4.2.xsd 
 http://www.springframework.org/schema/mvc 
 http://www.springframework.org/schema/mvc/spring-mvc-4.2.xsd 
 http://www.springframework.org/schema/context 
 http://www.springframework.org/schema/context/spring-context-4.2.xsd">

 <context:component-scan base-package="com.mengdee.manage.controller" />

 <bean id="viewresolver" class="org.springframework.web.servlet.view.internalresourceviewresolver"> 
 <property name="prefix" value="/"></property> <!-- 视图文件的前缀 --> 
 <property name="suffix" value=".jsp"></property> <!-- 视图文件的后缀名 --> 
 <!-- view是用什么显示，这里是jsp，还可以用velocity之类的 --> 
 <property name="viewclass" value="org.springframework.web.servlet.view.jstlview"></property> 
 </bean> 

 <!-- 启动spring mvc的注解功能，完成请求和注解pojo的映射 -->
 <mvc:annotation-driven>
 <mvc:message-converters register-defaults="true">
 <!-- 配置fastjson 替换原来的jackson支持 -->
 <bean class="com.alibaba.fastjson.support.spring.fastjsonhttpmessageconverter">
 <property name="supportedmediatypes">
 <list>
 <value>text/html;charset=utf-8</value>
 <value>application/json</value>
 </list>
 </property>
 <property name="features">
 <list>

 <value>quotefieldnames</value> <!-- 输出key时是否使用双引号,默认为true -->
 <value>writemapnullvalue</value> <!-- 是否输出值为null的字段,默认为false -->

 <!-- 
 <value>disablecircularreferencedetect</value>
 <value>writedateusedateformat</value> 
 <value>writenullstringasempty</value> 字符类型字段如果为null,输出为"",而非null 
 <value>writenullnumberaszero</value> 数值字段如果为null,输出为0,而非null 
 <value>writenullbooleanasfalse</value> boolean字段如果为null,输出为false,而非null 
 <value>writenulllistasempty</value> list字段如果为null,输出为[],而非null
 -->

 </list>
 </property>
 </bean>
 </mvc:message-converters>
 </mvc:annotation-driven>
</beans> 

4、java

education:学历(枚举类)

package com.mengdee.manage.entity;
import java.util.hashmap;
import java.util.map;
/**
 * 学历
 * @author administrator
 *
 */
public enum education {
 kindergarten("幼儿园", 1),
 elementary("小学", 2),
 junior_middle("初级中学", 3),
 senior_middle("高级中学", 4),
 university("大学", 5),
 college("学院", 6);
 private static final map<integer, education> education_map = new hashmap<integer, education>();
 static {
 for (education education : education.values()) {
 education_map.put(education.getindex(), education);
 }
 }

 private string text;
 private int index;

 private education(string text, int index) {
 this.text = text;
 this.index = index;
 }


 public string gettext() {
 return text;
 }

 public void settext(string text) {
 this.text = text;
 }

 public int getindex() {
 return index;
 }

 public void setindex(int index) {
 this.index = index;
 }


 public static education getenum(integer index) {
 return education_map.get(index);
 }
}

person:

package com.mengdee.manage.entity;
import java.util.arraylist;
import java.util.date;
import java.util.list;
import java.util.map;
import com.alibaba.fastjson.annotation.jsonfield;
public class person {

 private long id;
 private string name;

 private byte gender; // 性别 1：男 2：女
 private short age; // 年龄
 private long salary; // 薪水
 private double weight; // 体重
 private char level; // 评级

 private boolean adult; // 是否成年人
 private date birthday; // 生日
 private education education;// 学历

 private string[] hobbies; // 爱好
 private list<dog> dogs; // 宠物狗
 private map<string, object> address; // 住址

 // 使用注解控制是否要序列化
 @jsonfield(serialize = false)
 private list<object> obj = new arraylist<>();

 public person() {

 }
 public person(long id, string name, byte gender, short age, long salary, double weight, char level, boolean adult,
 date birthday, string[] hobbies, list<dog> dogs, map<string, object> address) {
 super();
 this.id = id;
 this.name = name;
 this.gender = gender;
 this.age = age;
 this.salary = salary;
 this.weight = weight;
 this.level = level;
 this.adult = adult;
 this.birthday = birthday;
 this.hobbies = hobbies;
 this.dogs = dogs;
 this.address = address;
 }


 public long getid() {
 return id;
 }
 public void setid(long id) {
 this.id = id;
 }
 public string getname() {
 return name;
 }
 public void setname(string name) {
 this.name = name;
 }
 public byte getgender() {
 return gender;
 }
 public void setgender(byte gender) {
 this.gender = gender;
 }
 public short getage() {
 return age;
 }
 public void setage(short age) {
 this.age = age;
 }
 public long getsalary() {
 return salary;
 }
 public void setsalary(long salary) {
 this.salary = salary;
 }
 public double getweight() {
 return weight;
 }
 public void setweight(double weight) {
 this.weight = weight;
 }
 public char getlevel() {
 return level;
 }
 public void setlevel(char level) {
 this.level = level;
 }
 public boolean isadult() {
 return adult;
 }
 public void setadult(boolean adult) {
 this.adult = adult;
 }
 public date getbirthday() {
 return birthday;
 }
 public void setbirthday(date birthday) {
 this.birthday = birthday;
 }

 // 处理序列化枚举类型，默认的值是序列化枚举值字符串，而不是枚举绑定的索引或者文本
 @jsonfield(name = "edu")
 public int getedu(){
 return education.getindex();
 }

 @jsonfield(name = "edu")
 public void setedu(int index){
 this.education = education.getenum(index);
 }

 @jsonfield(serialize = false)
 public education geteducation() {
 return education;
 }

 @jsonfield(serialize = false)
 public void seteducation(education education) {
 this.education = education;
 }


 public string[] gethobbies() {
 return hobbies;
 }
 public void sethobbies(string[] hobbies) {
 this.hobbies = hobbies;
 }
 public list<dog> getdogs() {
 return dogs;
 }
 public void setdogs(list<dog> dogs) {
 this.dogs = dogs;
 }
 public map<string, object> getaddress() {
 return address;
 }
 public void setaddress(map<string, object> address) {
 this.address = address;
 }
}

testcontroller

package com.mengdee.manage.controller;

import java.text.decimalformat;
import java.util.arraylist;
import java.util.date;
import java.util.hashmap;
import java.util.list;
import java.util.map;

import org.springframework.stereotype.controller;
import org.springframework.web.bind.annotation.requestmapping;
import org.springframework.web.bind.annotation.responsebody;

import com.alibaba.fastjson.json;
import com.alibaba.fastjson.jsonarray;
import com.alibaba.fastjson.serializer.doubleserializer;
import com.alibaba.fastjson.serializer.serializeconfig;
import com.alibaba.fastjson.serializer.simpledateformatserializer;
import com.mengdee.manage.entity.address;
import com.mengdee.manage.entity.dog;
import com.mengdee.manage.entity.education;
import com.mengdee.manage.entity.person;

@controller
public class testcontroller {
 private static serializeconfig serializeconfig = new serializeconfig(); 
 static {
 serializeconfig.put(date.class, new simpledateformatserializer("yyyy-mm-dd hh:mm:ss")); 
 serializeconfig.put(double.class, new doubleserializer(new decimalformat("0.00")));
 }


 @requestmapping("/index")
 public string index(){
 return "index";
 }


 // javabean to object
 @requestmapping("/json")
 @responsebody
 public object json(){
 person person = new person();
 person.setid(1l);
 person.setname("mengdee");
 person.setage((short) 18);

 // 
 /*
 {
 "birthday": null, 
 "weight": 0, 
 "dogs": null, 
 "adult": false, 
 "hobbies": null, 
 "education": null, 
 "id": 1, 
 "level": "", 
 "address": null, 
 "age": 18, 
 "name": "mengdee", 
 "gender": 0, 
 "salary": 0
 }
 */
 object personjson = json.tojson(person);
 return personjson;
 }

 // javabean to string
 @requestmapping("/json2")
 @responsebody
 public string json2(){
 person person = new person();
 person.setid(1l);
 person.setname("mengdee");
 person.setage((short) 18);

 // 使用该方式值为null的经测试不出来，已经配置了<value>writemapnullvalue</value>
// "{"adult":false,"age":18,"gender":0,"id":1,"level":"","name":"mengdee","salary":0,"weight":0.0}"
 string jsonstring = json.tojsonstring(person);
 return jsonstring;
 }

 @requestmapping("/json3")
 @responsebody
 public object json3(){
 person person = new person();
 person.setid(1l);
 person.setname("mengdee");
 person.setage((short) 18);
 person.setbirthday(new date()); 

 object personjson = json.tojson(person); // json.tojson(person)默认是毫秒数"birthday":1495073314780,

// 使用serializeconfig序列号配置对日期格式化
// "{"birthday":"2017-05-18 10:19:55","weight":0.0,"adult":false,"id":1,"level":"","age":18,"name":"mengdee","gender":0,"salary":0}"
 string jsonstring = json.tojsonstring(personjson, serializeconfig);
 return jsonstring;
 }


 @requestmapping("/json4")
 @responsebody
 public object json4(){
 person person = new person();
 person.setid(1l);
 person.setname("mengdee");
 person.setage((short) 18);
 person.setbirthday(new date()); 
 person.seteducation(education.university); // 枚举

 string[] hobbies = {"读书", "旅游"};
 person.sethobbies(hobbies);

 dog dog1 = new dog(1l, "dog1", (short)1);
 dog dog2 = new dog(2l, "dog2", (short)2);
 list<dog> dogs = new arraylist<>();
 dogs.add(dog1);
 dogs.add(dog2);
 person.setdogs(dogs);

 address address1 = new address(1l, "上海浦东新区");
 address address2 = new address(2l, "上海宝山区");
 map<string, object> addressmap = new hashmap<>();
 addressmap.put(address1.getid() + "", address1);
 addressmap.put(address2.getid() + "", address2);
 person.setaddress(addressmap);



 object personjson = json.tojson(person);

 return personjson;
 }

 @requestmapping("/json5")
 @responsebody
 public string json5(){
 dog dog1 = new dog(1l, "dog1", (short)1);
 dog dog2 = new dog(2l, "dog2", (short)2);
 list<dog> dogs = new arraylist<>();
 dogs.add(dog1);
 dogs.add(dog2);

 // list<t> -> json
 string jsonstring = json.tojsonstring(dogs, false);
 system.out.println(jsonstring);

 // json -> list<t> 
 list<dog> parsearray = json.parsearray(jsonstring, dog.class);
 for (dog dog : parsearray) {
 system.out.println(dog);
 }

 map<string,dog> map = new hashmap<string, dog>(); 
 map.put("dog1",new dog(1l, "dog1", (short)1)); 
 map.put("dog2",new dog(2l, "dog2", (short)2)); 
 map.put("dog3",new dog(3l, "dog3", (short)3)); 

 // map -> json
 string mapjsonstring = json.tojsonstring(map,true); 
 system.out.println(mapjsonstring); 

 // json -> map 
 @suppresswarnings("unchecked")
 map<string,dog> map1 = (map<string,dog>)json.parse(mapjsonstring); 
 for (string key : map1.keyset()) { 
 system.out.println(key + ":" + map1.get(key)); 
 }

 // array -> json
 string[] hobbies = {"a","b","c"}; 
 string hobbiesstring = json.tojsonstring(hobbies,true); 
 system.out.println(hobbies); 

 // json -> array
 jsonarray jsonarray = json.parsearray(hobbiesstring); 
 for (object o : jsonarray) { 
 system.out.println(o); 
 } 
 system.out.println(jsonarray); 
 return jsonstring;
 }
}

swagger集成

第一步：引入相关依赖

<dependency>
 <groupid>io.springfox</groupid>
 <artifactid>springfox-swagger2</artifactid>
 <version>2.6.1</version>
 <scope>compile</scope>
</dependency>
<dependency>
 <groupid>com.fasterxml.jackson.core</groupid>
 <artifactid>jackson-databind</artifactid>
 <version>2.6.6</version>
</dependency>

第二步：swagger信息配置

swaggerconfig.java

@configuration
@enablewebmvc
@enableswagger2
public class swaggerconfig {
 @bean
 public docket customdocket() {
 docket docket = new docket(documentationtype.swagger_2);
 docket.apiinfo(apiinfo());
 docket.select().apis(requesthandlerselectors.withmethodannotation(apioperation.class));
 docket.select().paths(pathselectors.regex("/api/.*")).build();

 return docket;
 }

 private apiinfo apiinfo() {
 contact contact = new contact("小明", "http://www.baidu.com", "[e-mail]");
 return new apiinfo("api接口", //大标题 title
 "api接口", //小标题
 "0.0.1", //版本
 "www.baidu.com",//termsofserviceurl
 contact,//作者
 "api接口",//链接显示文字
 "http://www.baidu.com"//网站链接
 );
 }
}

注意：因swaggerconfig这个类配置了注解，所以这个类必须被扫描到，即该类一定包含在context:component-scan中。

第三步：在类、方法、参数上使用注解

@controller
@requestmapping("/api/v1")
@api(description = "api接口")
public class apicontroller {
 @apioperation(value = "用户登录", notes = "用户登录接口")
 @apiresponses({
 @apiresponse(code = 0, message = "success"),
 @apiresponse(code = 10001, message = "用户名错误", response = illegalargumentexception.class),
 @apiresponse(code = 10002, message = "密码错误")
 })
 @requestmapping(value = "/user/login", method = requestmethod.post, produces = {"application/json;charset=utf-8;"})
 @responsebody
 public string login(@apiparam(name = "username", value = "用户名", required = true) @requestparam string username,
  @apiparam(name = "password", value = "密码", required = true) @requestparam string password){
 return "{'username':'" + username + "', 'password':'" + password + "'}";
 }


 @apiimplicitparams({
 @apiimplicitparam(paramtype = "header", name = "phone", datatype = "string", required = true, value = "手机号"),
 @apiimplicitparam(paramtype = "query", name = "nickname", datatype = "string", required = true, value = "nickname", defaultvalue = "双击666"),
 @apiimplicitparam(paramtype = "path", name = "platform", datatype = "string", required = true, value = "平台", defaultvalue = "pc"),
 @apiimplicitparam(paramtype = "body", name = "password", datatype = "string", required = true, value = "密码")
 })
 @requestmapping(value = "/{platform}/user/regist", method = requestmethod.post, produces = {"application/json;charset=utf-8;"})
 @responsebody
 public string regist(@requestheader string phone, @requestparam string nickname, @pathvariable string platform, @requestbody string password){
 return "{'username':'" + phone + "', 'nickname':'" + nickname + "', 'platform': '" + platform + "', 'password':'"+password+"'}";
 }

 @requestmapping(value = "/user/list", method = requestmethod.get, produces = {"application/json;charset=utf-8;"})
 @responsebody
 public string getuserlist(pager pager){
 return "[{'id': "+pager.getpage()+", 'username': 'zhangsan"+pager.getsize()+"'}]";
 }

 @requestmapping("/docs")
 @apiignore
 public string test(){
 return "api-docs";
 }
}

pager

public class pager {
 @apimodelproperty(value = "页码", required = true)
 private int page;
 @apimodelproperty(value = "每页条数", required = true)
 private int size;

 public pager() {
 }

 public int getpage() {
 return page;
 }

 public void setpage(int page) {
 this.page = page;
 }

 public int getsize() {
 return size;
 }

 public void setsize(int size) {
 this.size = size;
 }
}

常用注解：

• @api(description = “接口类的描述”)
• @apioperation(value = “接口方法的名称”, notes = “备注说明”)
• @apiparam(name = “参数名称”, value = “备注说明”, required = 是否必须)：标注在方法的参数上 用于描述参数的名称、备注、是否必须等信息
• @apiimplicitparam(paramtype = “query”, name = “password”, datatype = “string”, required = true, value = “密码”, defaultvalue = “123456”)用于描述方法的参数，标注在方法上，和@apiparam功能一样，只是标注的位置不同而已
       .paramtype：参数类型，即参数放在哪个地方
              .   header–>请求参数的获取：@requestheader，参数放在请求头
               .   query–>请求参数的获取：@requestparam，参数追加在url后面
               .   path（用于restful接口）–>请求参数的获取：@pathvariable
               .   body 使用@requestbody接收数据 post有效，参数放在请求体中
               .    form
      .name：参数名
      .datatype：参数的数据类型
      .required：参数是否必须传
      .value：参数的描述
      .defaultvalue：参数的默认值
• @apiimplicitparams： 用于包含多个@apiimplicitparam
• @apiresponse(code = 0, message = “success”),
       .code：响应码，例如400
       .message：信息，一般是对code的描述
       .response：抛出异常的类
• @apimodel：描述一个model的信息（这种一般用在post创建的时候，使用@requestbody这样的场景，请求参数无法使用@apiimplicitparam注解进行描述的时候）
       .@apimodelproperty：描述一个model的属性
                .   position 允许在模型中显式地排序属性。
                .   value 参数名称
                .   required 是否必须 boolean
                .   hidden 是否隐藏 boolean
                .   allowablevalues = “range[0, 1]” 一般用于指定参数的合法值
• @apiignore：用于或略该接口，不生成该接口的文档

第四步：访问/v2/api-docs

在浏览器*问http://localhost:8080/工程名称/v2/api-docs 如果有json内容，证明正常

第五步：下载swagger-ui

从github上下载，注意这里要选择下载v2.2.10（ （）），大于这个版本的集成方式不一样。

集成方法：将v2.2.10下的dist目录下的所有文件放到自己工程中静态文件中，并使用下面代码覆盖掉index.html中的脚本部分

<script type="text/javascript">
 var baseurl = "";
 $(function () {
  var url = window.location.search.match(/url=([^&]+)/);
  if (url && url.length > 1) {
  url = decodeuricomponent(url[1]);
  } else {
  //上面描述的api-docs地址
  url = baseurl + "/webapp/v2/api-docs";
  }

  // pre load translate...
  if (window.swaggertranslator) {
  window.swaggertranslator.translate();
  }
  window.swaggerui = new swaggerui({
  url: url,
  validatorurl: undefined,
  dom_id: "swagger-ui-container",
  supportedsubmitmethods: ['get', 'post', 'put', 'delete', 'patch'],
  oncomplete: function (swaggerapi, swaggerui) {

   if (typeof initoauth == "function") {
   initoauth({
    clientid: "your-client-id",
    clientsecret: "your-client-secret-if-required",
    realm: "your-realms",
    appname: "your-app-name",
    scopeseparator: ",",
    additionalquerystringparams: {}
   });
   }

   if (window.swaggertranslator) {
   window.swaggertranslator.translate();
   }

   $('pre code').each(function (i, e) {
   hljs.highlightblock(e)
   });

   addapikeyauthorization();
  },
  onfailure: function (data) {
   log("unable to load swaggerui");
  },
  docexpansion: "none",
  jsoneditor: false,
  apissorter: "alpha",
  defaultmodelrendering: 'schema',
  showrequestheaders: false
  });

  //这里可以添加权限认证，例如token
  function addapikeyauthorization() {
  var token = "you-token";
  var tokenheader = new swaggerclient.apikeyauthorization("token", token, "header");
  window.swaggerui.api.clientauthorizations.add("token", tokenheader);
  }

  window.swaggerui.load();
  function log() {
  if ('console' in window) {
   console.log.apply(console, arguments);
  }
  }
 });
 </script>

第六步：访问上面修改的那个index.html
http://localhost:8080/工程名称/static/third-party/swagger-ui/index.html

注意：因要访问静态资源，使用springmvc请确保静态资源能够被访问到，如果不能访问请做如下配置：

1、 在spring的配置文件中增加默认的servlet处理器

<!-- 过滤静态资源 -->
<mvc:default-servlet-handler/>

2、 在web.xml中增加要过滤的静态文件

<!-- 过滤静态资源 -->
<servlet-mapping>
 <servlet-name>default</servlet-name>
 <url-pattern>*.js</url-pattern>
 <url-pattern>*.css</url-pattern>
 <url-pattern>/assets/*"</url-pattern>
 <url-pattern>/images/*</url-pattern>
</servlet-mapping>

示例项目代码结构：

完整示例demo下载地址：

其他

关于spring-servlet.xml 和 applicationcontext.xml

springmvc 提供了两种配置文件 spring-servlet.xml 、 applicationcontext.xml
spring-servlet.xml 是controller级别的，作用范围是控制层，默认的名字是【servlet-name】-servlet.xml
默认是放在web-inf/目录下，springmvc会自动加载，也可以在web.xml中配置它的位置

<servlet>
 <servlet-name>spring-mvc</servlet-name>
 <servlet-class>org.springframework.web.servlet.dispatcherservlet</servlet-class>
 <init-param> 
 <param-name>contextconfiglocation</param-name> 
 <param-value>/web-inf/spring-servlet.xml</param-value> 
 </init-param>
 <load-on-startup>1</load-on-startup>
</servlet>

一般在spring-servlet.xml中配置一些和控制器相关的配置,如视图解析、静态资源文件的映射、返回结果的解析等

视图解析

• org.springframework.web.servlet.view.urlbasedviewresolver
• tiles3： org.springframework.web.servlet.view.tiles3.tilesconfigurer
• springmvc: org.springframework.web.servlet.view.internalresourceviewresolver，
• shiro: org.apache.shiro.spring.security.interceptor.authorizationattributesourceadvisor
• 上传 org.springframework.web.multipart.commons.commonsmultipartresolver，

静态资源映射

<mvc:resources location="/static/" mapping="/static/**" />
<mvc:resources location="/images/" mapping="/static/**" />
<mvc:resources location="/css/" mapping="/static/**" />
<mvc:resources location="/js/" mapping="/static/**" />
<mvc:resources location="/html/" mapping="/static/**" /> 
<mvc:resources location="/upload/" mapping="/static/**" />

org.springframework.context.support.resourcebundlemessagesource

返回结果的解析

• fastjson: com.alibaba.fastjson.support.spring.fastjsonhttpmessageconverter

3、applicationcontext.xml 是系统级别的配置，作用范围是系统上下文，它的初始化需要放到 web.xml 中的context-param中配置

<context-param>
 <param-name>contextconfiglocation</param-name>
 <param-value>classpath:conf/spring/spring-*.xml</param-value>
</context-param>

4、 关于applicationcontxt.xml，一般是按照功能拆成多个配置文件如：

• - applicationcontxt-base.xml // 基础
• - applicationcontxt-redis.xml // redis相关配置
• - applicationcontxt-shiro.xml // shiro 相关配置
• - applicationcontxt-dao.xml // 数据库相关配置
• - applicationcontxt-xxx.xml // xxx

总结

以上就是这篇文章的全部内容了，希望本文的内容对大家的学习或者工作具有一定的参考学习价值，如果有疑问大家可以留言交流，谢谢大家对的支持。