千锋教育-做有情怀、有良心、有品质的IT职业教育机构

400-811-9990
当前位置:千锋视频教程 > Java视频教程  >  Java技术之SpringMVC与Swagger2集成文档

Java技术之SpringMVC与Swagger2集成文档

时间:2018-01-19 15:22:56     来源:千锋视频教程 作者:Disen

  一、 Springfox-Swagger/Swagger2说明

  Swagger 是一系列对 RESTful 接口进行规范描述和页面展示的工具,通过 springfox-swagger 将 Swagger 与 Spring-MVC 整合, 可从代码中的注解获取信息, 并生成相应的文档. 效果如下所示。

图1.1 swagger –ui 效果图

  图1.1 swagger –ui 效果图

  目前 Swagger 的 api 版本规范已经更新到 3.0版本,考虑SpringMVC的版本,

  本方案集成2.0版本。另外,Swagger的数据格式采用了JSON和YAML,详情请参考官方文档 https://swagger.io/docs/。

  二、SpringMVC项目中集成Springfox-Swagger

  集成的前提,当前的项目已具备了SpringMVC或Restfull开发能力,同时支持返回ResponseBody的数据类型为json。

  1. Maven的pom.xml中添加依赖

代码-1

  2. 自定义Swagger配置类 - AppSwaagerConfig

package com.qfxa.swagger;

import java.util.ArrayList;
import java.util.List;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2 //必须启用
public class AppSwaggerConfig {

  @Bean
  public Docket api() {
         //声明额外请求的参数-根据项目情况,可以去掉
    ParameterBuilder tokenBuilder = new ParameterBuilder();
    List<Parameter> params = new ArrayList<Parameter>();

    tokenBuilder.name("Authorization")
        .description("令牌")
        .modelRef(new ModelRef("string"))
        .defaultValue("bearer")
        .parameterType("header")
        .required(false);

    params.add(tokenBuilder.build());

    return new Docket(DocumentationType.SWAGGER_2)
.select()
//必须添加请求控制器所在的包,用于扫描接口
     .apis(RequestHandlerSelectors.basePackage("com.qfxa.action"))
        .paths(PathSelectors.any())
        .build()
        .globalOperationParameters(params) //公开的请求参数[可选]
        .apiInfo(apiInfo()); //整个api接口描述[必须]
 
  }

  private ApiInfo apiInfo() {
   
    return new ApiInfoBuilder()
      .title("ssm 后台接口")
      .description("接口信息详情")
      .version("V0.1.0")
      .termsOfServiceUrl("") //术语
      .contact(new Contact("disen", "", "610039018@qq.com"))
      .license("")
      .licenseUrl("")
      .build();
   
  }
}

  [重要说明]: RequestHandlerSelectors.basePackage()方法来来指定API接口所在的包,而且这个包必须要被Spring容器扫描到。

  3. 在spring-mvc.xml文件中配置

代码-2

  4. 在控制器类中使用Swagger的注解

  在控制器类中,使用@Api、@ApiOperation、@ApiParam等注解来声明Api接口信息,方便在Swagger页面中显示。

  @Api在控制器类上使用,主要描述当前控制器类被API文档关注,用法如:

  @Api

  @Controller

  @RequestMapping("/api/user")

  public class UserAction{ }

  @ApiOperation很重要,主要描述API接口信息的,如:

  @Autowired

  UserService service;

  @ApiOperation(tags="list",value="获取所有的用户信息",httpMethod="GET",

  notes="get user list",code=1)

  @GetMapping(path="/list",produces="application/json;charset=utf-8")

  @ResponseBody

  public List list() {

  return service.findAll();

  }

其中tags声明接口的名称,value声明接口的功能,httpMethod声明当前请求接口的方法,notes声明备注信息。效果如图1.2所示。

图1.2 list接口的描述信息

  @ApiOperation用在有参数的接口上时,需要使用@ApiParam来声明接口参数,写法如下所示,效果如图1.3。

  @ApiOperation(tags="login",value="用户登录",httpMethod="POST",notes="用户登录")

  @PostMapping(value="/login",produces="application/json;charset=utf-8")

  @ResponseBody

  public User login(

  @ApiParam(name="loginName",required=true)String loginName,

  @ApiParam(name="loginPwd",required=true)String loginPwd,

  @ApiParam(name="token",required=true)String token) {

  return service.login(loginName, loginPwd);

  }

  参数token主要用于权限控制,案例中如果没有处理权限,可以略去。

图1.3 login接口信息

  三、运行项目

  项目运行起来后,可以按以下两种方式请求,显示接口的描述信息。建议以ui的方式显示接口信息。

  1. http://localhost:8080/ssmapp/v2/api-docs

  ssmapp是项目名,v2/api-docs是swagger中请求映射的路径。请求结果是以json数据格式显示所有api接口。内容如下:

{"swagger":"2.0","info":{"description":"接口信息详情","version":"V0.1.0","title":"ssm 后台接口","contact":{"name":"disen","email":"610039018@qq.com"},"license":{}},"host":"localhost:8080","basePath":"/ssmapp","tags":[{"name":"user-action","description":"User Action"}],"paths":{"/api/user/list":{"get":{"tags":["list"],"summary":"获取所有的用户信息","description":"get user list","operationId":"listUsingGET","consumes":["application/json"],"produces":["application/json;charset=utf-8"],"parameters":[{"name":"Authorization","in":"header","description":"令牌","required":false,"type":"string","default":"bearer"}],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/User"}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/api/user/login":{"post":{"tags":["login"],"summary":"用户登录","description":"用户登录","operationId":"loginUsingPOST","consumes":["application/json"],"produces":["application/json;charset=utf-8"],"parameters":[{"name":"Authorization","in":"header","description":"令牌","required":false,"type":"string","default":"bearer"},{"in":"body","name":"loginName","description":"loginName","required":true,"schema":{"type":"string"}},{"in":"body","name":"loginPwd","description":"loginPwd","required":true,"schema":{"type":"string"}},{"in":"body","name":"token","description":"token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/User"}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}}},"definitions":{"User":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"img":{"type":"string"},"name":{"type":"string"},"passwd":{"type":"string"},"phone":{"type":"string"}}}}}

  2. http://localhost:8080/ssmapp/swagger-ui.html

  以页面的方式显示所有的API接口信息,效果如图1.1所示。

  • 北京天丰利校区(总部):北京市海淀区宝盛北里西区28号天丰利商城4层
    北京沙河校区:北京市昌平区沙阳路18号北京科技职业技术学院广场服务楼2层、南区服务楼2层
    咨询电话:400-186-9990 010-82790226-801
    面授课程:全栈HTML5+培训、UI交互设计培训、PHP培训、JavaEE+云数据培训、大数据开发培训、VR/AR混合
    现实培训、Python培训、Linux云计算培训、软件测试培训、Android培训、iOS培训、好程序员
  • 深圳西部硅谷校区地址:深圳市宝安区宝安大道5010号深圳西部硅谷B座A区605-619
    深圳大学城校区地址:深圳市南山区留仙大道1201号大学城创客小镇16栋2楼、3楼
    咨询电话:0755-33582485-801(硅谷校区)0755-86660670-801(大学城校区)
    面授课程:全栈HTML5+培训、UI交互设计培训、PHP培训、JavaEE+云数据培训、Android培训、iOS培训
  • 上海校区地址:上海市宝山区同济支路199号智慧七立方3号楼2-4层
    咨询电话:400-627-7899 021-56166283/56166279
    面授课程:全栈HTML5+培训、UI交互设计培训、JavaEE+云数据培训、Android课程培训、iOS课程培训、好程序员
  • 郑州校区地址:郑州市金水区纬五路21号河南教育学院综合楼(经纬中学楼)7/8层
    咨询电话:0371-55191750 400-186-9990
    面授课程:全栈HTML5+培训、UI交互设计培训、PHP培训、JavaEE+云数据培训、Android课程培训、iOS课程培训
  • 广州校区地址:广州市天河区元岗路310号智汇park创意园E座5层
    咨询电话:020-22119207 400-186-9990
    面授课程:全栈HTML5+培训、JavaEE+云数据培训、Android课程培训、iOS课程培训
  • 大连校区地址:辽宁省大连市甘井子区软件园路2号东软信息学院B5座一楼
    咨询电话:0411-39026086 400-186-9990
    面授课程:全栈HTML5+培训、JavaEE+云数据培训、UI交互设计培训、Android课程培训、iOS课程培训
  • 武汉校区地址:武汉市光谷大道61号智慧园21号楼2层
    咨询电话:027-65523826
    面授课程:全栈HTML5+培训、JavaEE+云数据培训、Android课程培训、iOS课程培训
  • 成都校区地址:成都市武侯区科华北路62号力宝大厦N(北楼)18楼
    咨询电话:028-83178771
    面授课程:全栈HTML5+培训、UI交互设计培训、PHP培训、JavaEE+云数据培训、Android课程培训、iOS课程培训
  • 西安校区地址:西安市雁塔区高新六路52号立人科技C座西区4楼
    咨询电话:029-85260160
    面授课程:全栈HTML5+培训、JavaEE+云数据培训、Android课程培训
  • 杭州校区地址:浙江省杭州市江干区九堡旺田书画城A座4层
    咨询电话:0571-86893632 010-82790226-801
    面授课程:全栈HTML5+培训、JavaEE+云数据培训、Android课程培训、iOS课程培训
  • 青岛校区地址:青岛市市南区金坛路17号青岛职业技术学院南校区实训楼A4层
    咨询电话:0532-80910752/3 010-82790226-801
    面授课程:全栈HTML5+培训、UI交互设计培训、JavaEE+云数据培训、Android课程培训、iOS课程培训
  • 重庆校区地址:重庆市高新区科园一路2号大西洋国际12-1
    咨询电话:023-68883009
    面授课程:JavaEE+云数据课程培训
  • 长沙校区地址:湖南省长沙市岳麓区麓谷企业广场A2栋三单元306号
    咨询电话:0731-85513010/85513210
    面授课程:JavaEE+云数据课程培训
  • 哈尔滨校区地址:哈尔滨市松北区创新一路699号科技创新城19号楼五楼
    咨询电话:15663846969
    面授课程:全栈HTML5+培训
  • 千锋教育服务号

    了解千锋动态
    关注千锋教育服务号

  • 千锋互联服务号

    扫码匿名提建议
    直达CEO信箱