前提条件: 已引入spring以及spring mvc的包,并做好了相关配置，能够正常运行
一. pom中引入swagger相关的依赖
io.springfox
springfox-swagger2
2.5.0
com.fasterxml.jackson.core
jackson-annotations
org.slf4j
slf4j-api
org.springframework
spring-aop
org.springframework
spring-beans
org.springframework
spring-context
io.springfox
springfox-swagger-ui
2.5.0
io.swagger
swagger-annotations
1.5.9
io.springfox
springfox-staticdocs
2.5.0
com.fasterxml.jackson.core
jackson-annotations
org.slf4j
slf4j-api
com.fasterxml.jackson.dataformat
jackson-dataformat-yaml
joda-time
joda-time
com.fasterxml.jackson.core
jackson-databind
com.fasterxml.jackson.core
jackson-core
com.fasterxml.jackson.datatype
jackson-datatype-joda
二. web.xml中启用web容器的default servlet，将静态资源交由web容器处理(这里主要指html文件)
default
*.js
default
*.css
default
*.jpg
default
*.png
default
*.gif
default
*.html
default
*.wof
四. 创建ApplicationSwaggerConfig类
package apidoc;
import org.springframework.context.annotation.Bean;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
*
* @author pan
*
*/
@EnableSwagger2
public class ApplicationSwaggerConfig {
@Bean
public Docket addUserDocket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2);
Contact contact = new Contact("潘志勇", "", "[email protected]");
ApiInfo apiInfo = new ApiInfo("进销存管理系统", "WEB API文档", "V0.0.1", "", contact, "", "");
docket.apiInfo(apiInfo);
return docket;
}
}
三.spring mvc配置文件中加入如下配置
四. API编写测试
package com.qc.invoicing.controller;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
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 io.swagger.annotations.Api;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
@Controller
@RequestMapping(value = "/test", produces = { "application/json;charset=utf-8" })
@Api(value = "/test", description = "测试Contrler")
public class TestController {
@RequestMapping(value = "/restStyle/{id}", method = RequestMethod.GET)
@ApiOperation(notes = "/restStyle", httpMethod = "GET", value = "rest风格方法")
@ApiResponses(value = { @ApiResponse(code = 200, message = "正常操作", response = StringAPIResponse.class) })
@ResponseBody
public StringAPIResponse restStyle(@ApiParam(required = true, value = "主键") @PathVariable(value = "id") long id) {
System.err.println(id);
StringAPIResponse apiResponse = new StringAPIResponse();
apiResponse.setMsg("操作成功");
apiResponse.setData("你好");
return apiResponse;
}
@RequestMapping(value = "/getStyle", method = RequestMethod.GET)
@ApiOperation(notes = "/getStyle", httpMethod = "GET", value = "get风格方法")
@ApiResponses(value = { @ApiResponse(code = 200, message = "正常操作", response = StringAPIResponse.class) })
@ResponseBody
public StringAPIResponse getStyle(@ApiParam(required = true, value = "主键") @RequestParam("id") long id) {
System.err.println(id);
StringAPIResponse apiResponse = new StringAPIResponse();
apiResponse.setMsg("操作成功");
apiResponse.setData("你好");
return apiResponse;
}
@RequestMapping(value = "/postStyle", method = RequestMethod.POST)
@ApiOperation(notes = "/postStyle", httpMethod = "POST", value = "post风格方法")
@ApiResponses(value = { @ApiResponse(code = 200, message = "正常操作", response = StringAPIResponse.class) })
@ResponseBody
public StringAPIResponse postStyle(@ApiParam(required = true, value = "简单数据") @RequestBody SimpleData data) {
System.err.println(data.getName());
StringAPIResponse apiResponse = new StringAPIResponse();
apiResponse.setMsg("操作成功");
apiResponse.setData("你好");
return apiResponse;
}
@RequestMapping(value = "/traditionStyle", method = RequestMethod.GET, produces = { "application/xml;charset=utf-8" })
@ApiOperation(notes = "转入页面:/WEB-INF/jsp/test.jsp", httpMethod = "GET", value = "传统风格方法")
@ApiResponses(value = { @ApiResponse(code = 200, message = "正常操作", response = StringAPIResponse.class) })
public String traditionStyle() {
return "/test";
}
}
class SimpleData {
@ApiModelProperty(value = "主键", hidden = false)
private long id;
@ApiModelProperty(value = "名称", required = true)
private String name;
@ApiModelProperty(value = "年龄")
private int age;
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 int getAge() {
return age;
}
public void setAge(int age) {
this.age = age;
}
}
abstract class APIResponse {
@ApiModelProperty(value = "操作是否成功")
private boolean optSuc = true;
@ApiModelProperty(value = "操作失败时的提示信息")
private String msg;
@ApiModelProperty(value = "返回结果")
private T data;
public boolean isOptSuc() {
return optSuc;
}
public void setOptSuc(boolean optSuc) {
this.optSuc = optSuc;
}
public String getMsg() {
return msg;
}
public void setMsg(String msg) {
this.msg = msg;
}
public T getData() {
return data;
}
public void setData(T data) {
this.data = data;
}
}
class StringAPIResponse extends APIResponse {
}
五. 启动jetty(如果是使用maven命令运行web项目，请使用jetty作为web容器，否则无法访问swagger)
mvn jetty:run
//访问地址:
http://ip:端口/项目名/swagger-ui.html#/
例如：
http://localhost:9080/test-project/swagger-ui.html
结果：
Paste_Image.png