SpringBoot 使用Swagger2打造在线接口文档

详情：https://www.jianshu.com/p/7e543f0f0bd8

项目例子：

一、依赖

  <!--swagger2 -->
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>${swagger2.version}<ersion>
   </dependency>
   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>${swagger2.version}<ersion>
   </dependency>
<swagger2.version>2.6.1</swagger2.version>

二、结构

三、代码示例

package com.etc.zhongtian.controller;
import com.etc.zhongtian.domian.Constant;
import com.etc.zhongtian.domian.DataValidator;
import com.etc.zhongtian.domian.ResultBean;
import com.etc.zhongtian.domian.User;
import com.etc.zhongtian.service.UserService;
import freemarker.template.Template;
import io.swagger.annotations.*;
import org.apache.tomcat.util.http.fileupload.FileUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Page;
import org.springframework.stereotype.Controller;
import org.springframework.ui.freemarker.FreeMarkerTemplateUtils;
import org.springframework.web.bind.annotation.*;
import java.io.File;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;
import java.util.Map;

/**
 * @Description: 用户控制层
 */
@RestController
@RequestMapping("user")
@Api(value="用户controller",tags={"用户操作接口"})
public class UserController {

    @Autowired
    private UserService userService ; //用户服务

        @GetMapping("welcome")
        public String welcome(Map<String, Object> model) {
            model.put("time", new Date());
            model.put("message", "王聪");
            return "welcome";
        }

    /**
     * 用户查询
     *
     * password 密码
     *
     *    key      value
     * username    wangcc
     * password    123456
     * @return
     */
    @ApiOperation(value="获取用户列表", notes="无参数获取所有用户信息")
    @ApiResponses({ @ApiResponse(code = 1, message = "操作成功"),
            @ApiResponse(code = 0, message = "操作失败，服务器内部异常"),
            @ApiResponse(code = 303, message = "权限不足") })
    @GetMapping("get")
    public ResultBean queryUserAll(){
        ResultBean result = new ResultBean();
        List<User> dataAqiInfoList = new ArrayList<>();
        if (result.getCode() == Constant.RESULT_CODE_SUCCESS){
            dataAqiInfoList = userService.queryUserAll();
            return result.ok(dataAqiInfoList);
        }
        return  result;
    }
    /**
     * 分页查询用户列表
     * @param payload
     * @return
     */
    @ApiOperation(value="分页带参数查询用户", notes="分页带参数查询用户")
    @ApiResponses({ @ApiResponse(code = 1, message = "操作成功"),
            @ApiResponse(code = 0, message = "操作失败，服务器内部异常"),
            @ApiResponse(code = 303, message = "权限不足") })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageIndex", value = "页数", required = true, dataType = "String",paramType="query"),
            @ApiImplicitParam(name = "pageSize", value = "数量", required = true, dataType = "String",paramType="query")
    })
    @GetMapping("paging/query")
    public ResultBean<Page<User>> pageUsers(@RequestParam Map<String, Object> payload) {
        ResultBean result = DataValidator.validateMapData(payload, "pageIndex","pageSize");
        if (result.getCode() == Constant.RESULT_CODE_SUCCESS){
            User user = new User();
            user.setAge(payload.containsKey("age") ?payload.get("age") != null ? payload.get("age").toString():"":"" );
            user.setName(payload.containsKey("name") ?payload.get("name") != null ? payload.get("name").toString():"":"" );
            Page<User> pageSysUserInfo = userService.findBookCriteria(Integer.parseInt(payload.get("pageIndex") .toString())
                    ,Integer.parseInt(payload.get("pageSize").toString()),user);
            return result.ok(pageSysUserInfo);
        }
        return result;

}

    @ApiOperation(value="更新用户性别", notes="无参数获取所有用户信息")
    @ApiResponses({ @ApiResponse(code = 1, message = "操作成功"),
            @ApiResponse(code = 0, message = "操作失败，服务器内部异常"),
            @ApiResponse(code = 303, message = "权限不足") })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "String",paramType="query"),
            @ApiImplicitParam(name = "sex", value = "用户性别", required = true, dataType = "String",paramType="query")
    })
    @GetMapping("update")
    public ResultBean sdf(@RequestParam Map<String, Object> payload){
        ResultBean result = DataValidator.validateMapData(payload, "id","sex");
        if (result.getCode() == Constant.RESULT_CODE_SUCCESS){
            boolean dataAqiInfoList = userService.update(payload.get("id").toString(),payload.get("sex").toString());
            return result.ok(dataAqiInfoList);
        }
        return  result;
    }


}

package com.etc.zhongtian.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
 * @Description:
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket myDocket() {
     Docket docket = new Docket(DocumentationType.SWAGGER_2);
     ApiInfo apiInfo = new ApiInfo(  "中联技术文档",
             "如有疑问或者错误请联系下方邮箱：",
             "1.0",
             "apiDocs",
             "17636677609@qq.com",
             "",
             "");
     docket.apiInfo(apiInfo);
     return docket;
    }
}