如何写API接口文档

        所谓API接口文档里面的大体上都应该是由请求路径、请求方式、接口描述、请求参数、返回数据这么几部分组成的。

        为什么我们要写API接口文档?

        好处:

                1.它方便了前后端的交流还有沟通。

                2.API接口文档提供了详细的API信息和示例代码，使得开发者可以更快速、准确地使用API进行开发工作，提高开发效率和代码质量。

                3.文档化测试:根据文档的传输方式和传输数据的格式,验证API的输入和输出是否符合预期，帮助发现和解决潜在的问题。

                4.等等。

        使用场景:​​​​​​

团队开发：在一个团队中，不同的开发者可能需要协同开发和集成各种API。API接口文档可以作为开发者之间沟通和理解API的重要工具，确保团队成员在开发过程中遵循一致的接口规范，提高协作效率。

客户集成：如果你的产品或服务需要与其他系统进行集成，那么提供清晰、准确的API接口文档将非常重要。客户可以根据文档理解如何调用你的API，以便集成和使用你的产品或服务。

第三方开发者集成：如果你允许第三方开发者使用你的API，那么提供良好的API接口文档是吸引开发者的关键。文档应该详细说明如何获取API密钥、调用API的方式和参数，并提供示例代码或库，以便开发者更容易地集成和使用你的API。

自动化测试：API接口文档可以作为自动化测试的依据。测试团队可以根据文档编写测试用例来验证API的正确性和稳定性。文档中的示例代码可以帮助测试团队更好地理解API的期望行为，并编写有效的测试脚本。

接口版本管理：如果你的API需要进行版本升级或变更，API接口文档可以帮助开发者了解新版本的API如何与旧版本的API不同。文档中可以清楚地记录每个版本的变更和兼容性注意事项，帮助开发者适应接口的变化。

文档化工具：API接口文档可以作为一种工具使用，帮助开发者和团队更好地组织和管理API相关信息。可以使用各种工具和框架（如Swagger、Postman等）生成和维护API接口文档，提供方便的查阅和交互式测试功能。

                                                                                                                         --本段摘自:Chat JPT

        Swagger框架的原理是基于注解和反射，通过读取代码中的注解信息，动态生成API文档和交互式界面。

第一步:

导入依赖

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

SpringMVC集成Swagger，生成API接口文档的增强方案，已经被Spring官方集成

配置类WebMvcConfiguration

/**
 * 通过knife4j生成接口文档
 * 返回一个 Docket 实例，用于配置和生成接口文档
 * @return Docket实例
 */
@Bean
public Docket docket() {
    // 构建接口文档信息
    ApiInfo apiInfo = new ApiInfoBuilder()
        .title("项目接口文档") 
        .version("2.0")
        .description("项目接口文档")
        .build();

    // 构建 Docket 实例，用于配置和生成接口文档
    Docket docket = new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo) // 设置接口文档信息
        .select()
        .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/");
}

常用注释

 示例:

/**
 * 员工管理
 */
@RestController
@RequestMapping("/admin/employee")
@Slf4j
@Api(tags = "员工相关接口")//对类的说明
public class EmployeeController {

    @Autowired
    private EmployeeService employeeService;
    @Autowired
    private JwtProperties jwtProperties;

    /**
     * 登录
     *
     * @param employeeLoginDTO
     * @return
     */
    @ApiOperation("登录接口")//说明方法的用途
    @PostMapping("/login")
    @ApiImplicitParams({
            @ApiImplicitParam(name="员工登录DTO",value = "111",paramType = "body")//解释方法参数
    })//解释方法参数个数
    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();
    }

}