增强版Swagger介绍与使用(Springboot版)

目录

 

一 介绍

1.1 Swagger核心功能

二 Maven引入

1.2创建Swagger配置文件

         1.3  Controller与方法加入响应注解

三 特殊情况。

四 文档地址 https://doc.xiaominfo.com/knife4j/springboot.html

---

一 介绍

1.1 Swagger核心功能

该UI增强包主要包括两大核心功能：文档说明 和 在线调试

• 文档说明：根据Swagger的规范说明，详细列出接口文档的说明，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息，使用swagger-bootstrap-ui能根据该文档说明，对该接口的使用情况一目了然。
• 在线调试：提供在线接口联调的强大功能，自动解析当前接口参数,同时包含表单验证，调用参数可返回接口响应内容、headers、Curl请求命令实例、响应时间、响应状态码等信息，帮助开发者在线调试，而不必通过其他测试工具测试接口是否正确,简介、强大。

同时，swagger-bootstrap-ui在满足以上功能的同时，还提供了文档的增强功能，这些功能是官方swagger-ui所没有的，每一个增强的功能都是贴合实际,考虑到开发者的实际开发需要,是比不可少的功能，主要包括：

1. 个性化配置：通过个性化ui配置项，可自定义UI的相关显示信息
2. 离线文档：根据标准规范，生成的在线markdown离线文档，开发者可以进行拷贝生成markdown接口文档，通过其他第三方markdown转换工具转换成html或pdf，这样也可以放弃swagger2markdown组件
3. 接口排序：自1.8.5后，ui支持了接口排序功能，例如一个注册功能主要包含了多个步骤,可以根据swagger-bootstrap-ui提供的接口排序规则实现接口的排序，step化接口操作，方便其他开发者进行接口对接

二 Maven引入

<swagger-knife4j>2.0.1</swagger-knife4j>


<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>${swagger-knife4j}</version>
</dependency>

2.1创建Swagger配置文件

添加Swagger全局配置类Swagger2Config

@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Config {

    /**
     * 注入swagger基础配置对象
     * @return
     */
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("base.springboot.controller"))
                //为有@Api注解的Controller生成API文档
//                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();

    }


    /**
     * 页面基础info
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试管理端")
                .description("demo")
                .version("1.0")
                .build();
    }

}

注意这一项配置apis(RequestHandlerSelectors.basePackage("base.springboot.controller"))
括号里的路径得配置成你项目中Controller的路径

 

2.2 Controller与方法加入响应注解

@Controller
@Api(tags = "测试管理")
public class SwaggerDemoController {



    @ApiOperation("基本样例测试")
    @RequestMapping(value = "/demo", method = RequestMethod.GET)
    @ResponseBody
    public String demo() {
       return "测试成功";
    }



    @ApiOperation("基本样例测试")
    @RequestMapping(value = "/request", method = RequestMethod.GET)
    @ResponseBody
    public String demoRequest() {
        return "测试成功";
    }



}

然后运行访问http://localhost:8080/doc.html 地址 效果如下

入参类加注解

在类上加入@ApiModel("学习对象")

在字段名上加入@ApiModelProperty( notes = "学生名称")

 

效果如下

三 特殊情况。

1. List<Class>的入参情况,swagger是不支持List<Class> 这种的测试的，如果需要测试 使用Post方法即可

2. 上传多文件List的情况，目前swagger也不支持，我目前是采用分成多个对象 param1 file1,param2 file2, 如果超过两个，非得用List的情况，建议使用PostMan进行测试，当然这种场景我还没试过 也是网友推荐的方法

四 文档与代码样例地址 

文档https://doc.xiaominfo.com/knife4j/springboot.html

代码地址：

https://github.com/Arsense/java-training/tree/master/base-freemwork/base-springboot/src/main/java/base/springboot