SpringBoot整合Swagger提供接口文档

SpringBoot整合Swagger提供接口文档

博文地址：https://www.cnblogs.com/imchentiefeng/articles/springboot-swagger-config.html

gitee地址： SpringBoot整合Swagger提供接口文档

背景

​ SpringBoot作为最流行的Java开发框架，我们经常用来开发接口服务，因此需要有一份接口文档，供前端或调用方可以方便、正确的调用我们的接口，swagger2 是一个规范和完整的API文档框架，可用于辅助我们的spingBoot应用来生成接口文档。

使用

1、添加依赖

注意：这里使用的是Maven环境

在pom.xml文件中添加依赖：

        <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

说明：

• springfox-swagger2：检测spring的web请求信息，生成检测结果（json格式）。
• springfox-swagger-ui：根据springfox-swagger2生成的数据，生成可视化的友好页面。

2、配置

@Configuration
@EnableOpenApi
public class Swagger2Conf {
    @Bean
    public Docket getUserDocket(){
        ApiInfo apiInfo=new ApiInfoBuilder()
                .title("xxx系统接口文档")//api标题
                .description("xxx系统相关接口描述")//api描述
                .version("1.0.0")//版本号
                .contact("chentiefeng")//本API负责人的联系信息
                .build();
        return new Docket(DocumentationType.SWAGGER_2)//文档类型（swagger2）
                .apiInfo(apiInfo)//设置包含在json ResourceListing响应中的api元信息
                .select()//启动用于api选择的构建器
                .apis(RequestHandlerSelectors.any())//扫描接口的包（扫描所有包）
                .paths(PathSelectors.any())//路径过滤器（扫描所有路径）
                .build();
    }
}

说明：

• @EnableOpenApi：表示启用swagger

3、访问

通过访问：http://localhost:8080/v2/api-docs 可以看到json格式的相关api信息。

4、完善接口信息

通过在Controller中的接口方法上加上相关注解，可以完善接口的说明信息。

常用注解如下：

注解	使用的地方	用途
@Api	类/接口	描述类/接口主要用途
@ApiOperation	方法	描述方法的用途
@ApiImplicitParam	方法	用于描述接口的非对象参数
@ApiImplicitParams	方法	用于描述接口的非对象参数集
@ApiIgnore	类/方法/参数	Swagger 文档不会显示拥有该注解的接口
@ApiModel	参数实体类	可设置接口相关实体的描述
@ApiModelProperty	参数实体类属性	可设置实体属性的相关描述

UI展示

​ swagger官方提供的有swagger-ui，但是使用起来不够方便，我比较了多种基于swagger-ui封装的开源的ui，如：swagger-admin、swagger-mg-ui、swagger-collector、SwaggerLUI、knife4j，根据我个人的需要最终选择了knife4j，下面开始介绍如何使用。

​ Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,Knife4j的前身是swagger-bootstrap-ui。官方开源地址是：https://gitee.com/xiaoym/knife4j，官方在线示例地址：http://knife4j.xiaominfo.com/doc.html

1、添加依赖

由于我的是springBoot项目，所以引入的是springBoot对应的starter：

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

2、访问

启动项目，访问：http://localhost:8080/doc.html ，便可以看到knife4j封装的swagger的管理界面了。

注意

问题：使用Swagger生成在线API文档，如果想有详细的接口描述信息，需要使用Swagger的注解，会对代码造成侵入。

解决：有一个开源项目smart-doc，也是一个接口文档生成的工具，它是基于源码中java-doc标准注释生成接口文档，可以不对代码造成侵入，需要的小伙伴可以使用，smart-doc开源地址：https://gitee.com/smart-doc-team/smart-doc 。