SSM中Swagger的简单使用

简介

swagger是一个RESTFUL风格的web服务框架：主要还是写给前端看

使用步骤：

• 导入依赖：

 <!--springfox的核心jar包 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <artifactId>slf4j-api</artifactId>
                    <groupId>org.slf4j</groupId>
                </exclusion>
                <exclusion>
                    <artifactId>jackson-annotations</artifactId>
                    <groupId>com.fasterxml.jackson.core</groupId>
                </exclusion>
                <exclusion>
                    <artifactId>spring-aop</artifactId>
                    <groupId>org.springframework</groupId>
                </exclusion>
                <exclusion>
                    <artifactId>spring-context</artifactId>
                    <groupId>org.springframework</groupId>
                </exclusion>
                <exclusion>
                    <artifactId>spring-beans</artifactId>
                    <groupId>org.springframework</groupId>
                </exclusion>
            </exclusions>
        </dependency>
        <!--springfox-ui的jar包(里面包含了swagger的界面静态文件) -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

• springmvc配置文件中配置swagger的放行地址

<!--配置下 swagger 的地址放行-->
    <mvc:resources location="classpath:/META-INF/resources/" mapping="/swagger-ui.html"/>
    <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>

• 添加swagger的配置类（一定要和controller或web层在同一层，否则不会生效【spring和springmvc的优先级】）

package com.hs.controller.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
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;

@EnableSwagger2 //开启 swagger2
@EnableWebMvc//声明是 web 项目
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api(ApiInfo apiInfo) {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
//                .apis(RequestHandlerSelectors.any())
                .apis(RequestHandlerSelectors.basePackage("com.hs.controller"))
                .build()
                .apiInfo(apiInfo);
    }
    @Bean
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("时间管理项目Forest接口文档")
                .description("时间管理项目Forest接口测试")
                .version("1.0.0")
                .termsOfServiceUrl("")
                .license("Apache2.0")
                .licenseUrl("http://httpd.apache.org/docs/2.0/license.html")
                .build();
    }
}

• 在实体类中的注解配置

@ApiModel(description = "区域数据")//类上设置
public class Area implements CheckEmptyInterface{
  @ApiModelProperty(value = "区域主键,查询时返回",hidden = true)//成员变量上设置
  private Long id;
  @ApiModelProperty(value = "区域名字",required = true,example = "东城区")
  private String areaname;
  @ApiModelProperty(value = "父区域id",example = "1")
  private Long parentid;
  @ApiModelProperty(value = "状态,0 无效,1 有效",example = "1")
  private String status;
  @ApiModelProperty(value = "父区域名字,查询时返回",example = "东城区",hidden = true)
  private String parentname;//父区域名字, 冗余数据

• 在控制器中的注解配置

@RestController
@RequestMapping("/areas")
@Api(tags = "区域管理模块" )//在接口文档的 controller 名字前面显示
public class AreaController {
    @Autowired
    private AreaService areaService;

    @ApiOperation("添加区域")//方法上设置，在swagger的每个标签上显示
    @PutMapping("/area")
    //实体类用注解配置了，在这里就无须重新设置
    public R addArea(@RequestBody Area area) {
        areaService.addArea(area);
        return R.setOK(null);
    }

    @PostMapping("/area")
    @ApiOperation("更新区域")
    public R updateArea(@RequestBody Area area) {
        areaService.updateArea(area);
        return R.setOK(null);
    }

    @DeleteMapping("/area")
    @ApiOperation("根据 id 删除区域")
    @ApiImplicitParam(name = "ids",value = "主键",required = true)//参数注解方式1
    public R deleteAreas(@RequestParam String[] ids) {
        areaService.deleteAreas(Arrays.asList(ids));
        return R.setOK(null);
    }

    @GetMapping("/area/{id}")
    @ApiOperation("根据 id 查询区域")
    public R getAreaById(@ApiParam(name = "id",value = "主键",defaultValue = "1") @PathVariable Long id) {//参数注解方式2

        Area area = areaService.getAreaById(id);
        return R.setOK(area);
    }

    @GetMapping("/area/parent/{id}")
    @ApiOperation("根据 父id 查询子区域")
    public R getAreaByParentId(@ApiParam(name = "id",value = "父id") @PathVariable Long id) {
        List<Area> areaList = areaService.getAreaByParentId(id);
        return R.setOK(areaList);
    }
    @GetMapping("/areas")
    @ApiOperation("查询所有区域")
    public R getAllAreas(@ApiParam(name = "page",value = "第几页",defaultValue = "1") @RequestParam(defaultValue = "1") int page,@ApiParam(name = "limit",value = "每页数量",defaultValue = "10") @RequestParam(defaultValue = "10") int limit,@ApiParam(name = "exludeId",value = "被忽略的区域 id") @RequestParam String exludeId, @ApiParam(name = "areanname",value = "区域模糊名字")@RequestParam  String areanname,@ApiParam(name = "status",value = "状态",defaultValue = "-100") @RequestParam(defaultValue = "-100") int status) {
        PageInfo<Area> pageInfo = areaService.getAllAreas(page , limit, exludeId, areanname, status);
        return R.setOK(pageInfo);
    }

    @GetMapping("/areas/parent")
    @ApiOperation("查询所有父区域")
    public R getAllFirstParentAreas(@ApiParam(name = "status",value = "状态",defaultValue = "-100") @RequestParam(defaultValue = "-100") int status) {
        List<Area> areaList = areaService.getAllFirstParentAreas(status);
        return R.setOK(areaList);
    }

}

配置完成之后就可以使用swagger查看项目的接口文档了