springboot整合swagger

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的。

Swagger的maven依赖

	<!-- 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>

Swagger配置文件

package com.fc.test.system.config;
import com.fc.test.common.constant.ConstantConfig;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

/**
 * [简要描述]: 基于swagger2的配置

 * [详细描述]:
 *
 * @author zzc
 * @time 2018/9/3
 * @since v0.8
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestfulApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 true false
                .enable(ConstantConfig.swaggerEnable)
                .select()
                //控制层包目录
                .apis(RequestHandlerSelectors.basePackage("com.fc.test.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("系统文档-PDMS")
                .description("powered By zhouzaichun")
                .termsOfServiceUrl("")
                //.contact(contact)
                .version("1.0")
                .build();
    }
}

控制层

package com.fc.test.controller.user;

import com.fc.test.common.RespStatus;
import com.fc.test.common.RestResponse;
import com.fc.test.model.TSysUser;
import com.fc.test.service.TSysUserService;
import com.github.pagehelper.PageInfo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import javax.annotation.Resource;
import lombok.extern.slf4j.Slf4j;
import org.apache.shiro.authz.annotation.Logical;
import org.apache.shiro.authz.annotation.RequiresPermissions;
import org.apache.shiro.authz.annotation.RequiresRoles;
import org.springframework.web.bind.annotation.*;

/**
 * [简要描述]:Restful控制器 

 * [详细描述]:
 *
 * @author zzc
 * @time   2019/10/25
 * @since V0.1
 */
@Slf4j
@Api(value = "用户管理", tags = {"用户管理"})
@RestController
@RequestMapping("/api/v1/t/sys/user")
public class TSysUserController {
    @Resource
    private TSysUserService tSysUserService;
    @ApiOperation(value = "数据新增")
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功", response = String.class),
            @ApiResponse(code = 101, message = "数据校验未通过"),
            @ApiResponse(code = 999, message = "失败"),
            @ApiResponse(code = 1501, message = "用户令牌过期"),
    })
    @PostMapping
    public RestResponse add(@RequestBody TSysUser tSysUser) {
        String id = tSysUserService.saveTSysUser(tSysUser);
        return RestResponse.builder().respStatus(RespStatus.SUCCESS).respData(id).build();
    }
    @RequiresRoles(value = { "admin"},logical = Logical.OR)
    @ApiOperation(value = "数据删除")
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功", response = String.class),
            @ApiResponse(code = 101, message = "数据校验未通过"),
            @ApiResponse(code = 999, message = "失败"),
            @ApiResponse(code = 1501, message = "用户令牌过期"),
    })
    @DeleteMapping("/{id}")
    public RestResponse delete(@ApiParam(value = "数据id") @PathVariable String id) {
        tSysUserService.deleteTSysUserById(id);
        return RestResponse.ok();
    }
    @ApiOperation(value = "数据修改")
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功", response = String.class),
            @ApiResponse(code = 101, message = "数据校验未通过"),
            @ApiResponse(code = 999, message = "失败"),
            @ApiResponse(code = 1501, message = "用户令牌过期"),
    })
    @PutMapping
    public RestResponse update(@RequestBody TSysUser tSysUser) {
        tSysUserService.updateTSysUser(tSysUser);
        return RestResponse.ok();
    }
    @ApiOperation(value = "获取数据详情")
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功", response = TSysUser.class),
            @ApiResponse(code = 101, message = "数据校验未通过"),
            @ApiResponse(code = 999, message = "失败"),
            @ApiResponse(code = 1501, message = "用户令牌过期"),
    })
    @GetMapping("/{id}")
    public RestResponse detail(@ApiParam(value = "数据id") @PathVariable String id) {
       TSysUser tSysUser = tSysUserService.findTSysUserById(id);
       return RestResponse.builder().respStatus(RespStatus.SUCCESS).respData(tSysUser).build();
    }

    @ApiOperation(value = "获取数据列表")
    @ApiResponses({
            @ApiResponse(code = 200, message = "成功", response = TSysUser.class),
            @ApiResponse(code = 101, message = "数据校验未通过"),
            @ApiResponse(code = 999, message = "失败"),
            @ApiResponse(code = 1501, message = "用户令牌过期"),
    })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "page", value = "页数 "),
            @ApiImplicitParam(name = "size", value = "每页数量 "),
    })
    @GetMapping
    public RestResponse list(@RequestParam(defaultValue = "1") Integer page, @RequestParam(defaultValue = "10") Integer size) {
        PageInfo pageInfo = tSysUserService.findTSysUserList(page, size);
        return RestResponse.builder().respStatus(RespStatus.SUCCESS).respData(pageInfo).build();
    }
}

实体类

package com.fc.test.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import javax.persistence.*;
@Data
@ApiModel(description = "用户实体")
@Table(name = "t_sys_user")
public class TSysUser {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private String id;

    /**
     * 用户账号
     */
    @ApiModelProperty(value="用户账号",example="admin")
    private String username;

    /**
     * 用户密码
     */
    @ApiModelProperty(value="密码",example="123456")
    private String password;
}

过滤器放行

访问