SpringBoot整合Swagger-UI实现在线API文档

整合Swagger-UI实现在线API文档

Swagger2介绍:

​ Swagger-UI是HTML, Javascript, CSS的一个集合，可以动态地根据注解生成在线API文档。

常用注解:

@Api：用于修饰Controller类，生成Controller相关文档信息
@ApiOperation：用于修饰Controller类中的方法，生成接口方法相关文档信息
@ApiParam：用于修饰接口中的参数，生成接口参数相关文档信息
@ApiModelProperty：用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息

具体步骤如下:

1、在pom.xml中新增Swagger-UI相关依赖

<!--Swagger-UI API文档生产工具-->

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2、在Java代码中配置Swagger2

​ Swagger对生成API文档的范围有三种不同的选择

• 生成指定包下面的类的API文档
• 生成有指定注解的类的API文档
• 生成有指定注解的方法的API文档

package app.mall.config;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @className Swagger2Config
 * @author Echo
 * @description Swagger2 配置类
 *      UI页面  http://服务器ip:端口/swagger-ui.html
 * @updateTime 2021/11/13 17:00
 * @version 1.0
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    
    

    //是否开启swagger，正式环境一般是需要关闭的
    @Value(value = "${swagger.enabled}")
    Boolean swaggerEnabled;
    @Bean
    public Docket createRestApi(){
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下controller生成API文档	--你的项目基础包名
                .apis(RequestHandlerSelectors.basePackage("app.mall.controller")) 
                //为有@Api注解的Controller生成API文档
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
    
    
        return new ApiInfoBuilder()
                .title("HincIturAdAstra-Mall")
                .description("api接口文档")
                .version("1.0")
                .build();
    }
}