Swagger2 集成 Swagger-Bootstrap-Ui 生成美化文档

Swagger-Bootstrap-Ui 使Swagger2默认模板更佳简洁好看

只有三步就可以完成配置
第一步 ：引入jar包
第二步 ：启动配置Swagger属性
第三步 ：使用注解编写文档

第一步 Maven 引入jar包

<!-- swagger2 配置 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

第二步 编写Java 配置启动Swagger组件

import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @name: Swagger2
 * @description: XXX
 * @type: JAVA
 * @since: 2020/12/23 15:07
 * @author: DuanLinPeng
 */
@Configuration
@EnableSwagger2 
public class Swagger2 {

 	// 访问的地址后面加上原swgger2
    // http://localhost:8080/swagger-ui.html#/
    // swagger-bootstrap-ui 插件改变风格
    // http://localhost:8080/doc.html#/

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("all")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.tuan.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket webApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("openApi")
                .apiInfo(webApiInfo())
                .select()
                //只显示api路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/index/.*")))
                .build();
    }

    @Bean
    public Docket adminApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                //只显示admin路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/redis/.*")))
                .build();

    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder().title("测试SWAGGER_2接口")
                .version("1.0.1")
                .description("项目演示学习")
                .contact(new Contact("Tuanlinpeng", "tuan.puls","1652376757@qq.com" ))
                .termsOfServiceUrl("https://tuan.plus")
                .build();
    }

    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("网站前台-API文档")
                .description("本文档描述了网站微服务接口定义")
                .version("1.0")
                .contact(new Contact("Tuan", "http://www.tuan.press", "z141111422@qq.com"))
                .build();
    }

    private ApiInfo adminApiInfo(){

        return new ApiInfoBuilder()
                .title("后台管理系统-API文档")
                .description("本文档描述了后台管理系统微服务接口定义")
                .version("1.0")
                .contact(new Contact("Helen", "http://www.tuan.press", "z141111422@qq.com"))
                .build();
    }

访问效果图

第三步 使用注解编写文档

注解	场景	说明
@Api	类	用来标注该类具体实现内容
@ApiOperation	方法	用来标注该方法具体实现内容
@ApiImplicitParams	方法	一个允许多个ApiImplicitParam对象列表的包装器
@ApiImplicitParam	方法	方法传入单个参数说明
@ApiModel	类	表示对类进行说明，用于参数用实体类接收 如：BO,FROM
@ApiModelProperty	方法、字段	对model属性的说明或者数据操作更改
@ApiOperation	方法	表示一个http请求的操作
@ApiResponses	方法	一个允许多个ApiResponse对象列表的包装器
@ApiResponse	方法	描述操作的可能响应
@ApiIgnore	类	忽略该类写入文档中

使用案例：

//测试类忽略写入------------------------------
@ApiIgnore
@RestController
@RequestMapping("/test")
public class TestConteroller

//返回状态------------------------------
@ApiResponses({
        @ApiResponse(code=400,message="请求参数没填好"),
        @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})

//请求说明------------------------------

@ApiOperation(value = "查询排序轮播图")
@GetMapping("/carousel")
public ResultBase queryAllCarouse(){
     List<Carousel> carousels = carouselService.queryAllCarouse(IsEnum.YES.getType());
     return ResultBase.ok(carousels);
}

//实体类接收说明 -------------------------
@ApiModel(value = "用户接受信息")
public class UserBO {
    @ApiModelProperty(value = "用户名 用户名",required = true)
    private String username;
    @ApiModelProperty(value = "密码 密码",required = true)
    private String password;
    @ApiModelProperty(value = "确认密码 密码",required = false)
    private String confirmPassword;
}

//方法参数接收说明 -------------------------
@PostMapping("queryPage")
    @ApiOperation(value = "查询商品评价信息分页")
    @ApiImplicitParams({@ApiImplicitParam(name = "itemId",value = "父级id",required = true),
                    @ApiImplicitParam(name = "level",value = "所属级别",required = true),
                    @ApiImplicitParam(name = "page",value = "当前页",dataType ="int"),
                    @ApiImplicitParam(name = "pageSize",value = "页大小",dataType = "int")})
    Page<ItemCommentVO> queryPagedComments(String itemId,
                                           Integer level,
                                           Integer page,
                                           Integer pageSize){
       return itemService.queryPagedComments(itemId, level, page, pageSize);
}
   
    
//api接口类说明 -------------------------
@RestController
@RequestMapping("/itemscomments")
@Api(value = "商品评价" ,tags = "商品评价相关")
public class ItemsCommentsController 

访问的地址后面加上原swgger2： http://localhost:8080/swagger-ui.html#/
swagger-bootstrap-ui 插件改变风格： http://localhost:8080/doc.html#/