Swagger与SpringMvc整合

介绍

Swagger2可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体， 可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试。

具体使用

导入坐标：

<!--springfox的核心jar包-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<!--springfox-ui的jar包(里面包含了swagger的界面静态文件)-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

创建Swagger2配置类

package com.mr.swagger;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableWebMvc
@EnableSwagger2
public class MySwaggerConfig {
    @Bean
    public Docket myDocket() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("MySwagger[Api接口文档]") // 标题
                .description("") // 描述
                .contact(new Contact("", "", "")) // 联系方式
                .version("1.0") // 版本号
                .build();
        docket.apiInfo(apiInfo);
        //设置只生成被Api这个注解注解过的Ctrl类中有ApiOperation注解的api接口的文档
        docket.select().apis(RequestHandlerSelectors.withClassAnnotation(Api.class)).apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
        return docket;
    }
}

添加配置

在 springmvc的xml配置文件中写入资源路径映射

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

在合适的地方添加注解

一般在Controller和Model中会用到注解，会用到的注解有

@Api：用在请求的Controller类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注释"

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="int"       
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
    这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

Controller示例代码

package com.mr.controller;

import com.mr.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;

/**
 * Created by xu on 2019/4/15.
 */
@Controller
@Api(tags = "用户模块")
public class TestController {



    //新增
    @RequestMapping(value = "user",method = RequestMethod.POST,produces = "application/json;charset=UTF-8")
    @ResponseBody
    @ApiOperation(value = "新增用户")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "id", value = "用户主键", required = false, dataType = "int"),
            @ApiImplicitParam(paramType = "query", name = "name", value = "用户名字", required = true, dataType = "string", defaultValue = "zxf")
    })
    public String addUser(User user){
        return "新增用户"+user;
    }

    //修改
    @RequestMapping(value = "user",method = RequestMethod.PUT,produces ="application/json;charset=UTF-8" )
    @ResponseBody
    @ApiOperation(value = "修改用户")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "id", value = "用户主键", required = false, dataType = "int"),
            @ApiImplicitParam(paramType = "query", name = "name", value = "用户名字", required = true, dataType = "string")
    })
    public String editUser(User user){
        return "修改用户"+user;
    }

    //删除
    @RequestMapping(value = "user",method = RequestMethod.DELETE,produces = "application/json;charset=UTF-8")
    @ResponseBody
    @ApiOperation(value = "删除用户")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "id", value = "用户主键", required = true, dataType = "int"),
    })
    public String deleteById(Integer id){
        return "删除用户"+id;
    }

    //根据id查询
    @RequestMapping(value = "user/{id}",method = RequestMethod.GET,produces = "application/json;charset=UTF-8")
    @ResponseBody
    @ApiOperation(value = "根据ID获得用户",notes = "test")
    @ApiImplicitParam(paramType = "path", name = "id", value = "用户主键", required = true, dataType = "int")
    public String selectUserById(@PathVariable("id") Integer id){
        return "根据主键查询id"+id;
    }

    //条件查询
    @RequestMapping(value = "user",method = RequestMethod.GET,produces = "application/json;charset=UTF-8")
    @ResponseBody
    @ApiOperation(value = "条件查询")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "id", value = "用户主键",  dataType = "int"),
            @ApiImplicitParam(paramType = "query", name = "name", value = "用户名字", dataType = "string")
    })
    public String selectUser(User user){
        return "条件查询"+user;
    }
}

展示结果：