Swagger-开发者社区

介绍

使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面。官网: API Documentation & Design Tools for Teams | Swagger

Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案，对Swagger进行了封装，简化了相应的操作

使用方式

导入Knife4j的maven坐标

<dependency> <groupld>com.github.xiaoymin</groupld> <artifactld>knife4j-spring-boot-starter</artifactld> <version>3.0.2</version> </dependency>

在配置类中加入knife4j相关配置

/** * 通过knife4j生成接口文档 * @return */ @Bean public Docket docket1() { ApiInfo apiInfo = new ApiInfoBuilder() .title("苍穹外卖项目接口文档") .version("2.0") .description("苍穹外卖项目接口文档") .build(); Docket docket = new Docket(DocumentationType.SWAGGER_2) .groupName("管理端接口") .apiInfo(apiInfo) .select() // 指定生成接口需要扫描的包 .apis(RequestHandlerSelectors.basePackage("com.sky.controller.admin")) .paths(PathSelectors.any()) .build(); return docket; } @Bean public Docket docket2() { ApiInfo apiInfo = new ApiInfoBuilder() .title("苍穹外卖项目接口文档") .version("2.0") .description("苍穹外卖项目接口文档") .build(); Docket docket = new Docket(DocumentationType.SWAGGER_2) .groupName("用户端接口") .apiInfo(apiInfo) .select() .apis(RequestHandlerSelectors.basePackage("com.sky.controller.user")) .paths(PathSelectors.any()) .build(); return docket; }

设置静态资源映射，否则接口文档页面无法访问

/** * 设置静态资源映射 * @param registry */ protected void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); }

这个是重写的 WebMvcConfigurationSupport 父类的方法

使用

启动项目后，在浏览器中输入 localhost:8080/doc.html 就能进入查看接口页面

之后就能在这里进行调试了

常见注解

@Api	用在类上，例如Controller，表示对类的说明
@ApiModel	用在类上，例如entity、DTO、VO
@ApiModelProperty	用在属性上，描述属性信息
@ApiOperation	用在方法上，例如Controller的方法，说明方法的用途、作用

例：

/** * 员工管理 */ @RestController @RequestMapping("/admin/employee") @Slf4j @Api(tags = "员工相关接口") public class EmployeeController { @Autowired private EmployeeService employeeService; @Autowired private JwtProperties jwtProperties; /** * 登录 * * @param employeeLoginDTO * @return */ @PostMapping("/login") @ApiOperation("员工登录") public Result<EmployeeLoginVO> login(@RequestBody EmployeeLoginDTO employeeLoginDTO) { log.info("员工登录：{}", employeeLoginDTO); Employee employee = employeeService.login(employeeLoginDTO); //登录成功后，生成jwt令牌 Map<String, Object> claims = new HashMap<>(); claims.put(JwtClaimsConstant.EMP_ID, employee.getId()); String token = JwtUtil.createJWT( jwtProperties.getAdminSecretKey(), jwtProperties.getAdminTtl(), claims); EmployeeLoginVO employeeLoginVO = EmployeeLoginVO.builder() .id(employee.getId()) .userName(employee.getUsername()) .name(employee.getName()) .token(token) .build(); return Result.success(employeeLoginVO); } /** * 退出 * * @return */ @PostMapping("/logout") @ApiOperation("员工退出") public Result<String> logout() { return Result.success(); } /** * 新增员工 * @param employeeDTO * @return */ @PostMapping @ApiOperation("新增员工") public Result save(@RequestBody EmployeeDTO employeeDTO){ log.info("新增员工，员工数据：{}",employeeDTO); employeeService.save(employeeDTO); return Result.success(); } /** * 员工分页查询 * @param employeePageQueryDTO * @return */ @GetMapping("/page") @ApiOperation("员工分页查询") public Result page(EmployeePageQueryDTO employeePageQueryDTO){ log.info("员工分页查询：{}",employeePageQueryDTO); PageResult pageResult = employeeService.pageQuery(employeePageQueryDTO); return Result.success(pageResult); } /** * 启用禁用员工账号 * @param status * @param id * @return */ @PostMapping("/status/{status}") @ApiOperation("启用禁用员工账号") public Result startOrStop(@PathVariable Integer status, Long id){ log.info("员工状态：{}，员工id：{}",status,id); employeeService.startOrStop(status,id); return Result.success(); } /** * 根据id查询员工信息 * @param id * @return */ @GetMapping("/{id}") @ApiOperation("根据id查询员工信息") public Result<Employee> getById(@PathVariable Long id){ log.info("根据id查询员工信息：{}",id); Employee employee = employeeService.getById(id); return Result.success(employee); } /** * 编辑员工信息 * @param employeeDTO * @return */ @PutMapping @ApiOperation("编辑员工信息") public Result update(@RequestBody EmployeeDTO employeeDTO){ log.info("编辑员工信息：{}",employeeDTO); employeeService.update(employeeDTO); return Result.success(); } }

@Data @ApiModel(description = "员工登录时传递的数据模型") public class EmployeeLoginDTO implements Serializable { @ApiModelProperty("用户名") private String username; @ApiModelProperty("密码") private String password; }