swagger2 配置 生成接口文档

共4步：1.配置依赖jar包==》2.启动类添加启动注解@EnableSwagger2==>3.Swagger2Config配置文件 和 访问入口配置文件==》4.配置controller类

访问：http://localhost:端口号/swagger-ui.html

1.依赖

        <!--8.接口文档生成-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

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

2.启动类注解

@EnableSwagger2
@EnableTransactionManagement // 启注解事务管理，等同于xml配置方式的 <tx:annotation-driven />
@SpringBootApplication
@MapperScan("com.test.springboot.example.mapper")
@EnableCaching  //开启缓存
public class SpringbootApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringbootApplication.class, args);
        while (true) {
            Scanner scan = new Scanner(System.in);
            String question = scan.nextLine();
            String answer = question.replace('你', '我').replace('吗', ' ').replace('？', '!');
            out.println(answer);

        }
    }
}

3.2个配置文件

基本配置

package com.test.springboot.config;

import com.test.springboot.bean.ResultModel;
import io.swagger.annotations.*;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMethod;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.time.LocalDate;
import java.util.ArrayList;
import java.util.List;

/**
 * @author zh
 * @ClassName cn.saytime.Swgger2
 * @Description
 * @date 2017-07-10 22:12:31
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
//访问：http://localhost:端口号/swagger-ui.html
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("中国组")//
                .directModelSubstitute(LocalDate.class, String.class)//
                .genericModelSubstitutes(ResponseEntity.class)//
                .useDefaultResponseMessages(false)//
                .globalResponseMessage(RequestMethod.POST, ResultModel.customerResponseMessage())//设置POST方法返回值
                .globalResponseMessage(RequestMethod.GET, ResultModel.customerResponseMessage())//
                .globalResponseMessage(RequestMethod.DELETE, ResultModel.customerResponseMessage())//
                .globalResponseMessage(RequestMethod.PUT, ResultModel.customerResponseMessage())//
                .forCodeGeneration(true)//
                .select()//
                .apis(RequestHandlerSelectors.basePackage("com.test.springboot.example.controller"))//扫描的包
                //.apis(RequestHandlerSelectors.basePackage("com.test.springboot.example.controller"))//扫描的包
                .paths(PathSelectors.any())//
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")//标题
                .version("1.0")//版本
                .description("简单优雅的restfun风格，http://blog.csdn.net/saytime")//文档总述
                .termsOfServiceUrl("http://blog.csdn.net/saytime")//
                .license("222222")//
                .contact("3333333")//

                .build();
    }




//    @Api：修饰整个类，描述Controller的作用
//    @ApiOperation：描述一个类的一个方法，或者说一个接口
//    @ApiParam：单个参数描述
//    @ApiModel：用对象来接收参数
//    @ApiProperty：用对象接收参数时，描述对象的一个字段
//    @ApiResponse：HTTP响应其中1个描述
//    @ApiResponses：HTTP响应整体描述
//    @ApiIgnore：使用该注解忽略这个API
//    @ApiError ：发生错误返回的信息
//    @ApiImplicitParam：一个请求参数
//    @ApiImplicitParams：多个请求参数
}

访问入口配置文件

//静态资源拦截器
package com.test.springboot.config;
import com.test.springboot.util.LinusFileUtil;
import com.test.springboot.util.Log;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

/**
 * @Company:wftdlx
 * @Author: wjf  提示:拦截器  必须放置在一个文件中
 * @Description: 拦截器类
 * @Date: Created in 15:19 2018/12/19
 */
@Configuration
public class InterceptorConfig extends WebMvcConfigurationSupport {


    //查询图片
    //静态资源拦截  http://192.168.1.7:9091/files/文件名
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        Log.info("静态资源拦截 imageUrl ====" + LinusFileUtil.imageUrl+"静态资源拦截 projectUrl ===="+ LinusFileUtil.projectUrl);
        registry.addResourceHandler("/picture/imageShow/**").addResourceLocations("file:" + LinusFileUtil.imageUrl);//自定义路径访问
        registry.addResourceHandler("/picture/projectShow/**").addResourceLocations("file:" + LinusFileUtil.projectUrl);//工程路径访问
        super.addResourceHandlers(registry);

        //swagger2使用
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        //swagger2使用
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

4.controller层

注意必须restful风格（否则可能生成同一个接口的get，post等方法）

@Api：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

    *  code：数字，例如400

    *  message：信息，例如"请求参数没填好"

    *  response：抛出异常的类   

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

    *  @ApiModelProperty：描述一个model的属性

注意：@ApiImplicitParam的参数说明：

paramType：指定参数放在哪个地方	header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）-->请求参数的获取：@PathVariable body：（不常用） form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传	true | false
value：说明参数的意思
defaultValue：参数的默认值

package com.test.springboot.example.controller;

import com.alibaba.fastjson.JSON;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.sun.org.apache.bcel.internal.generic.NEW;
import com.test.springboot.bean.ResultModel;
import com.test.springboot.example.ennity.User;
import com.test.springboot.example.mapper.UserMapper;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import netscape.security.UserTarget;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;
import java.util.List;

/**
 * @Company:wftdlx
 * @Author: wjf
 * @Description:
 * @Date: Created in 11:28 2019/5/13
 */
@Controller
@RequestMapping("/restful")
public class RestfulController {
    @Resource
    UserMapper userMapper;

    //    paramType：指定参数放在哪个地方：
//    1.header：请求参数放置于Request Header，使用@RequestHeader获取
//    2.query：请求参数放置于请求地址，使用@RequestParam获取
//    3.path：（用于restful接口）-->请求参数的获取：@PathVariable
//    4.body：（不常用）
//    5.form（不常用）
    //查询
    @ApiOperation(value = "查询一个用户详情", notes = "根据url的id来获取用户详细信息") //API 方法说明 ： value--小标题  notes--详细说明
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
// 用在方法上包含一组参数说明。 paramType:参数放在哪个地方
    @GetMapping("/user/{id}") //映射地址
    @ResponseBody //异步json数据
    public ResultModel select(@PathVariable(name = "id") Integer id) {//@PathVariable 获取url中的变量
        User user = userMapper.selectById(id);
        return new ResultModel(ResultModel.SUCCESS, "查询成功", user);
    }


    //查询
    @ApiOperation(value = "查询一个用户详情", notes = "根据入参id来获取用户详细信息") //API 方法说明 ： value--小标题  notes--详细说明
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")// 用在方法上包含一组参数说明。 paramType:参数放在哪个地方
    @GetMapping("/users") //映射地址
    @ResponseBody //异步json数据
    public ResultModel selects(@PathVariable(name = "id") Integer id) {//@PathVariable 获取url中的变量
        User user = userMapper.selectById(id);
        return new ResultModel(ResultModel.SUCCESS, "查询成功", user);
    }

    //增加
    @ApiOperation(value = "增加用户", notes = "根据入参User对象增加用户")
    @ApiImplicitParam(name = "user", value = "用户对象user", required = true, dataType = "User")
    @PostMapping("/user")//仅仅可以使用post方法
    @ResponseBody //返回 异步json数据
    public ResultModel demo1(@RequestBody User user) {//接收json请求数据；必须post请求；仅仅一个；int数据可以使用引号或者不用；对象属性不用全写；@RequestParam()可以同时使用而且可以多个
        //正确结果
        int insert = userMapper.insert(user);
        //排错
        if (insert > 0) {
            return new ResultModel(ResultModel.SUCCESS, "增加成功", user);
        }
        return new ResultModel(ResultModel.ERROR, "增加失败", insert);
    }

    //删除
    @ApiOperation(value = "删除一个用户", notes = "根据url的id来指定删除用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
    @RequestMapping(value = "/user/{id}", method = RequestMethod.DELETE, produces = "application/json;charset=UTF-8")
    @ResponseBody //返回 异步json数据
    public ResultModel delete(@PathVariable(name = "id") Integer id) {//接收json请求数据；必须post请求；仅仅一个；int数据可以使用引号或者不用；对象属性不用全写；@RequestParam()可以同时使用而且可以多个
        int i = userMapper.deleteById(id);
        //排错
        if (i > 0) {
            return new ResultModel(ResultModel.SUCCESS, "删除成功");

        }
        return new ResultModel(ResultModel.ERROR, "删除失败", i);
    }


    //修改
    @ApiOperation(value = "修改用户", notes = "根据url的id来修改用户信息")
    @ApiImplicitParam(name = "user", value = "用户对象", required = true, dataType = "User")
    @RequestMapping(value = "/user", method = RequestMethod.PATCH, produces = "application/json;charset=UTF-8")
    @ResponseBody //返回 异步json数据
    public ResultModel patch(@RequestBody User user) {
        int i = userMapper.updateById(user);
        if (i > 0) {
            return new ResultModel(ResultModel.SUCCESS, "修改成功", user);
        } else {
            return new ResultModel(ResultModel.ERROR, "修改失败", i);
        }
    }

    /**
     * 根据id修改用户信息
     *
     * @param user
     * @return
     */
    @ApiOperation(value = "修改用户", notes = "根据url的id来修改用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
    })
    @RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
    public ResultModel update(@PathVariable("id") Integer id, @RequestBody User user) {
        QueryWrapper<User> userQueryWrapper = new QueryWrapper<>();
        userQueryWrapper.eq("id", id);
        int update = userMapper.update(user, userQueryWrapper);
        if (update > 0) {
            return new ResultModel(ResultModel.SUCCESS, "修改成功", update);
        } else {
            return new ResultModel(ResultModel.ERROR, "修改失败", update);
        }
    }

}