Swagger技术生成接口文档并测试 API及MD5加密方法

简介：整理自黑马程序员苍穹外卖p14

介绍

Swagger 是一个用于设计、构建、记录和使用 RESTful API 的工具集。它提供了一种标准化的方式来描述 API，帮助开发者理解和使用接口。

1. 基本概念

• API 文档：Swagger 使用 OpenAPI 规范（OAS），这是一种描述 RESTful API 的标准格式，允许 API 提供者定义其功能、输入/输出格式、错误代码等信息。
• Swagger UI：一个自动生成的用户界面，展示 API 文档，允许用户通过图形界面进行 API 调用。
• Swagger Editor：一个在线工具，允许开发者编写和编辑 API 定义，并即时预览生成的文档。
• Swagger Codegen：可以根据 API 定义生成客户端和服务器端的代码框架，支持多种编程语言。

2. 主要功能

• API 设计：Swagger 提供了一种可视化的方式来设计和修改 API。开发者可以使用 Swagger Editor 来创建和调整 API 的结构。

• 交互式文档：Swagger UI 使得 API 文档更易于理解，用户可以直接在界面上测试 API，而无需使用 Postman 或其他工具。

• 自动化生成：通过 Swagger Codegen，可以快速生成项目所需的代码，有助于提高开发效率，减少手动编码的工作量。

• 版本控制和一致性：通过将 API 定义文件（如 YAML 或 JSON 格式）纳入版本控制，可以确保 API 的一致性和可追溯性。

3. 使用场景

• 团队协作：在团队开发中，Swagger 可以帮助不同角色（如前端开发者、后端开发者、测试人员）更好地沟通和理解 API。
• API 测试：开发者和测试人员可以使用 Swagger UI 直接测试 API，快速验证其功能是否正常。
• 客户端开发：通过生成客户端 SDK，减少了与后端交互时的重复工作，使得前端开发更加高效。

4. 优点

• 易于使用：Swagger 提供友好的界面，降低了 API 文档的理解难度。
• 开源社区：作为一个开源项目，Swagger 拥有广泛的社区支持，提供丰富的插件和工具。
• 跨语言支持：Swagger 兼容多种编程语言和框架，可以应用于不同技术栈的项目。

5. 总结

Swagger 是一个 powerful 的工具，为开发者提供了一种标准化的方式来设计和使用 API，通过它可以提高开发效率、减少错误并改善团队协作。无论是在开发初期的设计阶段，还是在后期的文档和测试阶段，Swagger 都发挥着重要作用。

使用方式

Yapi网址：YYApi Pro-高效、易用、功能强大的可视化接口管理平台

apifox网址：Apifox - API 文档、调试、Mock、测试一体化协作平台。拥有接口文档管理、接口调试、Mock、自动化测试等功能，接口开发、测试、联调效率，提升 10 倍。最好用的接口文档管理工具，接口自动化测试工具。

常用注解

Swagger接口文档小技巧

拦截器配置类

package com.sky.config;

import com.sky.interceptor.JwtTokenAdminInterceptor;
import com.sky.json.JacksonObjectMapper;
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.http.converter.HttpMessageConverter;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
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;

import java.util.List;

/**
 * 配置类，注册web层相关组件
 */
@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {

    @Autowired
    private JwtTokenAdminInterceptor jwtTokenAdminInterceptor;

    /**
     * 注册自定义拦截器
     *
     * @param registry
     */
    protected void addInterceptors(InterceptorRegistry registry) {
        log.info("开始注册自定义拦截器...");
        registry.addInterceptor(jwtTokenAdminInterceptor)
                .addPathPatterns("/admin/**")
                .excludePathPatterns("/admin/employee/login");
    }

    /**
     * 通过knife4j生成接口文档(扫描controller包下的不同包，将管理端controller与用户端controller在接口文档中分开)
     * @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/");
    }


    /**
     * 扩展Spring MVC框架的消息转换器
     * @param converters
     */
    @Override
    protected void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
        //创建一个消息转换器对象

        MappingJackson2HttpMessageConverter converter = new MappingJackson2HttpMessageConverter();
        //需要为消息转换器设置一个对象转换器，对象转换器可以将Java对象序列化为json数据
        converter.setObjectMapper(new JacksonObjectMapper());
        //将自己的消息转换器加入容器中(因为converters拥有自带的消息转换器，所以设置索引为0可以优先使用自己的消息转换器)
        converters.add(0,converter);
    }
}

MD5加密