SpringBoot使用Swagger2搭建强大的RESTful API 文档功能

提示：扫一扫查出行
【扫一扫了解最新限行尾号】
复制提示

swagger用于定义API文档。

Swagger2的使用

Maven Plugin添加Swagger2相关jar包

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>

添加Swagger2配置文件

package com.goku.webapi.config.Swagger; import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2; /**
* Created by nbfujx on 2017-11-14.
*/
@Configuration
@EnableSwagger2
public class Swagger2Config { @Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.goku.webapi.controller"))
.paths(PathSelectors.any())
.build();
} private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Goku.WebService.Simple")
.description("Goku.WebService.Simple")
.termsOfServiceUrl("https://github.com/nbfujx")
.contact("nbfujx")
.version("1.0")
.build();
}
}

添加文档内容

在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。如下所示，我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。同时可以使用@ApiIgnore来过滤一些不需要展示的接口。

package com.goku.webapi.controller.impl; import com.alibaba.fastjson.JSON;
import com.goku.webapi.controller.loginController;
import com.goku.webapi.util.enums.returnCode;
import com.goku.webapi.util.message.returnMsg;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.apache.shiro.SecurityUtils;
import org.apache.shiro.authc.AuthenticationException;
import org.apache.shiro.authc.UsernamePasswordToken;
import org.apache.shiro.crypto.hash.Md5Hash;
import org.apache.shiro.session.SessionException;
import org.apache.shiro.subject.Subject;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.web.ErrorAttributes;
import org.springframework.boot.autoconfigure.web.ErrorController;
import org.springframework.http.HttpStatus;
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.RestController;
import org.springframework.web.context.request.RequestAttributes;
import org.springframework.web.context.request.ServletRequestAttributes;
import springfox.documentation.annotations.ApiIgnore; import javax.servlet.http.HttpServletRequest;
import java.util.HashMap;
import java.util.Map; /**
* Created by nbfujx on 2017-11-07.
*/
@RestController
@Api(value="登录验证")
public class loginControllerImpl implements loginController,ErrorController { private final static String ERROR_PATH = "/error"; @Autowired
private ErrorAttributes errorAttributes; @ApiOperation(value="用户登录", notes="用户登录校验")
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "String" ,paramType="query"),
@ApiImplicitParam(name = "password", value = "密码", required = true, dataType = "String" ,paramType="query"),
@ApiImplicitParam(name = "rememberMe", value = "记住用户", required = true, dataType = "String" ,paramType="query")
})
@RequestMapping(value = "/login", method = RequestMethod.POST)
public String login(
@RequestParam(value = "username", required = true) String userName,
@RequestParam(value = "password", required = true) String password,
@RequestParam(value = "rememberMe", required = true, defaultValue = "false") boolean rememberMe
) {
String passwordmd5 = new Md5Hash(password, "2").toString();
Subject subject = SecurityUtils.getSubject();
UsernamePasswordToken token = new UsernamePasswordToken(userName, passwordmd5);
token.setRememberMe(rememberMe);
try {
subject.login(token);
} catch (AuthenticationException e) {
e.printStackTrace();
return JSON.toJSONString (new returnMsg(returnCode.ERROR));
}
return JSON.toJSONString (new returnMsg(returnCode.SUCCESS));
} @Override
@RequestMapping(value = "/logout", method = RequestMethod.POST)
@ApiOperation(value="用户退出", notes="用户退出校验")
public String logout() {
Subject subject = SecurityUtils.getSubject();
try {
subject.logout();
}catch (SessionException e){
e.printStackTrace();
return JSON.toJSONString (new returnMsg(returnCode.ERROR));
}
return JSON.toJSONString (new returnMsg(returnCode.SUCCESS));
} @Override
@RequestMapping(value = "/notAuthc", method = RequestMethod.GET)
@ApiIgnore
public String notAuthc() {
return JSON.toJSONString (new returnMsg(returnCode.NOTAUTHC));
} @Override
@RequestMapping(value = "/notAuthz", method = RequestMethod.GET)
@ApiIgnore
public String notAuthz() {
return JSON.toJSONString (new returnMsg(returnCode.NOTAUTHZ));
} @Override
@RequestMapping(value =ERROR_PATH)
@ApiIgnore
public String error(HttpServletRequest request)
{
Map<String, Object> body = getErrorAttributes(request, getTraceParameter(request));
return JSON.toJSONString (new returnMsg(returnCode.ERROR,body));
} @Override
public String getErrorPath() {
return ERROR_PATH;
} private boolean getTraceParameter(HttpServletRequest request) {
String parameter = request.getParameter("trace");
if (parameter == null) {
return false;
}
return !"false".equals(parameter.toLowerCase());
} private Map<String, Object> getErrorAttributes(HttpServletRequest request,boolean includeStackTrace) {
RequestAttributes requestAttributes = new ServletRequestAttributes(request);
Map<String, Object> map = this.errorAttributes.getErrorAttributes(requestAttributes,includeStackTrace);
String URL = request.getRequestURL().toString();
map.put("URL", URL);
return map;
} }

完成上述代码添加上，启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html

注解说明：

@Api：用在类上，说明该类的作用
@ApiOperation：用在方法上，说明方法的作用
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
- paramType：参数放在哪个地方
  - header-->请求参数的获取：@RequestHeader
  - query-->请求参数的获取：@RequestParam
  - path（用于restful接口）-->请求参数的获取：@PathVariable
  - body（不常用）
  - form（不常用）
- name：参数名
- dataType：参数类型
- required：参数是否必须传
- value：参数的意思
- defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
- code：数字，例如400
- message：信息，例如"请求参数没填好"
- response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
- @ApiModelProperty：描述一个model的属性