Swagger-1-与SpringMVC整合

我不是女神ヾ 2022-02-19 06:00 198阅读 0赞

## 介绍 ##

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

## 具体使用 ##

### 导入坐标 ###

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.8.0</version>
    </dependency>
    
    <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.user.controller;
    
    import com.mr.user.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;
    
    import java.util.Date;
    
    @Controller
    @Api(tags = "用户模块")
    public class SwaggerController {
    
        @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 User test2(@PathVariable("id") Integer id){
            User u = new User();
            u.setUserid(id);
            u.setUsername("明瑞教育");
            u.setUserage(18);
            u.setUserdate(new Date());
            return u;
        }
    
        @RequestMapping(value = "user",method = RequestMethod.POST, produces = "text/html;charset=UTF-8")
        @ResponseBody
        @ApiOperation(value = "新增用户")
        @ApiImplicitParams({
                @ApiImplicitParam(paramType = "query", name = "username", value = "用户名", required = true, dataType = "string"),
                @ApiImplicitParam(paramType = "query", name = "userage", value = "用户年龄", required = true, dataType = "int", defaultValue = "18"),
                @ApiImplicitParam(paramType = "query", name = "userdate", value = "生日,格式如:2019-09-09", required = true)
        })
        public String test3(User user){
            return "新增用户-" + user;
        }
    
        @RequestMapping(value = "user",method = RequestMethod.PUT, produces = "text/html;charset=UTF-8")
        @ResponseBody
        @ApiOperation(value = "修改用户")
        @ApiImplicitParams({
                @ApiImplicitParam(paramType = "query", name = "userid", value = "用户主键", required = true, dataType = "int"),
                @ApiImplicitParam(paramType = "query", name = "username", value = "用户名", required = true, dataType = "string"),
                @ApiImplicitParam(paramType = "query", name = "userage", value = "用户年龄", required = true, dataType = "int"),
                @ApiImplicitParam(paramType = "query", name = "userdate", value = "生日,格式如:2019-09-09", required = true)
        })
        public String test4(User user){
            return "修改用户-" + user;
        }
    
        @RequestMapping(value = "user",method = RequestMethod.DELETE, produces = "text/html;charset=UTF-8")
        @ResponseBody
        @ApiOperation(value = "删除用户")
        @ApiImplicitParam(paramType = "query", name = "id", value = "用户主键", required = true, dataType = "int")
        public String test5(Integer id){
            return "删除用户ID-" + id;
        }
    
        @RequestMapping(value = "user",method = RequestMethod.GET, produces = "text/html;charset=UTF-8")
        @ResponseBody
        @ApiOperation(value = "条件查询用户")
        @ApiImplicitParams({
                @ApiImplicitParam(paramType = "query", name = "userid", value = "用户主键", dataType = "int"),
                @ApiImplicitParam(paramType = "query", name = "username", value = "用户名", dataType = "string"),
                @ApiImplicitParam(paramType = "query", name = "userage", value = "用户年龄", dataType = "int"),
                @ApiImplicitParam(paramType = "query", name = "userdate", value = "生日,格式如:2019-09-09")
        })
        public String test6(User user){
            return "条件查询-" + user;
        }
    
    }

### 展示效果 ###

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDkxNDc4NA_size_16_color_FFFFFF_t_70]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDkxNDc4NA_size_16_color_FFFFFF_t_70]: /images/20220219/0d58e14783e64b33973cd2dd14719d57.png