后端 API 接口文档 Swagger 使用

Swagger 是什么

swagger是一款可以根据 restful 风格生成的接口开发文档，并且支持做测试的一款中间软件。
例如当我们在开发前后端分离项目时，当后端开发完一个功能想要测试时，若此时还没有相应的前端页面发起请求，可以通过 swagger 进行测试(功能类似于 postman)。

使用

这里以 knife4j 为例演示下怎么使用（knife4j可以看作是Swagger的升级版，但是界面比Swagger更好看，功能更丰富）。

导入坐标

首先需要在 pom.xml 中导入 knife4j 坐标，如下

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId></dependency>

配置

package com.sky.config;import lombok.extern.slf4j.Slf4j;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.web.servlet.config.annotation.InterceptorRegistry;import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;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;/** * 配置类，注册web层相关组件 */@Configuration@Slf4jpublic class WebMvcConfiguration extends WebMvcConfigurationSupport {/** * 通过knife4j生成接口文档 * @return */@Beanpublic Docket docket() {ApiInfo apiInfo = new ApiInfoBuilder().title("苍穹外卖项目接口文档").version("2.0").description("苍穹外卖项目接口文档").build();Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo).select()//指定扫描的包路径来定义指定要建立API文档的控制器类或方法.apis(RequestHandlerSelectors.basePackage("com.sky.controller")).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/");}}

编写 Controller

package com.sky.controller.admin;import com.sky.constant.JwtClaimsConstant;import com.sky.dto.EmployeeLoginDTO;import com.sky.entity.Employee;import com.sky.properties.JwtProperties;import com.sky.result.Result;import com.sky.service.EmployeeService;import com.sky.utils.JwtUtil;import com.sky.vo.EmployeeLoginVO;import lombok.extern.slf4j.Slf4j;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.web.bind.annotation.PostMapping;import org.springframework.web.bind.annotation.RequestBody;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RestController;import java.util.HashMap;import java.util.Map;/** * 员工管理 */@RestController@RequestMapping("/admin/employee")@Slf4jpublic class EmployeeController {@Autowiredprivate EmployeeService employeeService;@Autowiredprivate JwtProperties jwtProperties;/** * 登录 * * @param employeeLoginDTO * @return */@PostMapping("/login")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")public Result<String> logout() {return Result.success();}}

结果

将 springboot 项目运行成功后在浏览器中输入 localhost:8080/doc.html 即可看到下面结果（这里的8080需要根据实际情况换成自己项目对应的端口号）。

测试

这里常使用一个不存在的账号登录，可以看到相应内容里面显示 “账号不存在”。