java中如何使用Swagger生成在线接口文档

java中如何使用Swagger工具生成在线接口文档

文章目录

前言

一、Swagger、Knife4j是什么？

二、java中如何使用Knife4j

1.在pom.xml文件中引入knife4j的maven坐标

2.配置类中加入knife4j的相关配置

3.设置静态资源映射

4.项目实战

总结

---

---

前言

  Swagger是由美国软件公司SmartBear Software开发的一种用于描述和定义RESTful API的工具。目前，Swagger已经成为了API开发和管理领域中最流行的工具之一，被广泛应用于各种软件开发项目中。

---

一、Swagger、Knife4j是什么？

· Swagger是一种用于描述和定义RESTful API的工具和规范。它可以让开发人员更加方便地描述API的请求和响应结构、参数、错误码等信息，同时也能够生成交互式的API文档和客户端代码。通过使用Swagger，开发人员可以更加规范和标准化地设计和管理API，从而提高API的可读性、可维护性和可测试性。
· Knife4j是为 java MVC 框架集成Swagger生成API文档的增强解决方案

二、java中如何使用Knife4j

1.在pom.xml文件中引入knife4j的maven坐标

代码如下：

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

2.配置类中加入knife4j的相关配置

代码如下：

@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {
    @Bean
    public Docket docket() {
        log.info("准备生成接口文档...");
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("项目接口文档")
                .version("2.0")
                .description("项目接口文档")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName("api")
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller.admin"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

· 此处创建的 WebMvcConfiguration类 继承自 WebMvcConfigurationSupport 是SpringMVC提供的扩展类，用于提供拦截器、资源处理器等注册功能。

· 在声明的 docket 方法上加上 @bean 注解，此时由spring框架创建 Docket 对象并由 spring框架管理

· 创建ApiInfo对象，对象中的属性title、version、description为自定义的基本信息

· 创建Docket对象，此时对象中的属性groupName、apiInfo设置接口文档信息，已经创建好apiInfo对象直接调用，默认调用方法select  最重要的是apis方法（指定生成接口文档需要扫描的包，当下我扫描的是controller层下的admin）paths固定写法 

3.设置静态资源映射

@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {
    @Bean
    public Docket docket() {
        log.info("准备生成接口文档...");
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("项目接口文档")
                .version("2.0")
                .description("项目接口文档")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName("api")
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller.admin"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }   
    /**
     * 设置静态资源映射
     * @param registry
     */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        log.info("开始设置静态资源映射...");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

· 设置静态资源映射，否则接口文档页面无法显示

· 通过重写 WebMvcConfigurationSupport 父类中的 addResourceHandlers 方法 将我们的/doc.html 和 /webjars/**路径请求映射到类路径下的固定路径中，也就是说生成的接口文档都会放到这些路径中。

4.项目实战

· Swagger常用注解@Api( tags = "  " ) 和     @ApiOperation( "  " )

· 注解@Api( tags = "  " )放在Controller类的上方，@ApiOperation( "  " )则放在方法的上方

  

总结

Swagger是在开发阶段使用到的框架，目的是为了帮助后端开发人员做后端的接口测试

· 使用Swagger注解可以使接口文档有更高的可读性。最常使用的@Api( tags = "  " ) 和     @ApiOperation( "  " )