SpringBoot整合Swagger2

Swagger2
在前端还没写好时，我们想进行后台测试数据时，比如传入值到后台或者显示后台的结果到页面，这时我们可以使用 Postman或者Swagger2来进行测试。
swagger是什么
1、是一款让你更好的书写API文档的规范且完整框架。

2、提供描述、生产、消费和可视化RESTful Web Service。

3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

这里使用Swagger2在Springboot上进行简单的使用
依赖

<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>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

第一个是API获取的包，第二是官方给出的一个ui界面。
这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。

自定义一个Docket的Bean

@Configuration
@EnableSwagger2
public class Swagger2 {

        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.yss.ms.admin"))
                    .paths(PathSelectors.any())
                    .build();
        }

       private ApiInfo apiInfo() {        return new ApiInfoBuilder()
                .title("接口列表 v1.1.0") // 任意，请稍微规范点
                .description("接口测试") // 任意，请稍微规范点
                .termsOfServiceUrl("http://localhost:8080/swagger-ui.html") // 将“url”换成自己的ip:port
                .contact("zsl") // 无所谓（这里是作者的别称）
                .version("1.1.0")
                .build();
    }


    }

apiInfo中，主要配置一下Swagger2文档网站的信息，例如网站的title，网站的描述，联系人的信息，使用的协议等等。

在你要测试的controller的接口上加上Swagger2相关注解

@Api(description = "知识分类相关接口")
@RestController
public class KnowledgeSortsApi implements Apis {
    @Autowired
    private IKnowledgeSortsService knowledgeSortsService;
    @ApiOperation(value = "查询知识点分类", notes = "根据查询条件,分页查询知识点分类列表")
    @PostMapping(ADMIN_KNOWLEDGE_SORTS_PAGE_QUERY)
    public Resp<Page<KnowledgeSortsPageResult>> pageQueryList(@ApiParam(value = "分页查询条件", required = true) @RequestBody KnowledgeSortsPageDto knowledgeSortsPageDto) {
        Page<KnowledgeSortsPageResult> pageResult = knowledgeSortsService.pageQueryList(knowledgeSortsPageDto);
        return Resp.success(pageResult);
    }
    @ApiOperation(value = "知识点分类下一级树查询", notes = "根据父级id查询下一级分类树,默认查询所有分类")
    @ApiImplicitParam(name = "parentId", value = "知识点分类上级Id", required = false, paramType = "form", dataType = "long", defaultValue = "1")
    @GetMapping(API_KNOWLEDGE_SORTS_LIST)
    public Resp<KnowledgeSortListResult> getKnowledgeSortsList(@RequestParam(required = false, defaultValue = "1") Long parentId) {
        KnowledgeSortListResult knowledgeSortListResult = knowledgeSortsService.getKnowledgeSortsList(parentId);
        return Resp.success(knowledgeSortListResult);
    }
 
}

public class KnowledgeSortTreeResult implements Serializable{
    @ApiModelProperty(value = "知识点分类Id",required = true)
    private Long id;
    @ApiModelProperty(value = "知识点分类状态", required = true)
    private int knowledgeSortsStatus;
    @ApiModelProperty(value = "知识点分类名称", required = true)
    private String knowledgeSortsName;
    @ApiModelProperty(value = "知识点分类排序", required = true)
    private Integer knowledgeSortsSort;
    @ApiModelProperty(value = "知识点分类下一级树", required = true)
    private List<KnowledgeSortTreeResult> children = Lists.newArrayList();
}

public class KnowledgeSortsPageDto extends Pageable implements Serializable {
    @Comment("分类id")
    @ApiModelProperty(value = "知识点分类Id", required = false, example = "2")
    private Long knowledgeSortsId;
    @Comment("分类编码")
    @ApiModelProperty(value = "知识点分类编码", required = false, example = "")
    private String knowledgeSortsCode;
    @Comment("分类名称")
    @ApiModelProperty(value = "知识点分类名称", required = false, example = "")
    private String knowledgeSortsName;
    @ApiModelProperty(value = "知识点分类状态", required = false, example = "1")
    @Comment("分类状态")
    private Integer knowledgeSortsStatus;
}

public class KnowledgeSortsPageResult implements Serializable{
    @ApiModelProperty(name = "id", value = "知识点分类Id", required = true)
    private long id;
    @ApiModelProperty(value = "知识点分类编码", required = true)
    private String knowledgeSortsCode;
    @ApiModelProperty(value = "知识点分类名称", required = true)
    private String knowledgeSortsName;
    @ApiModelProperty(value = "知识点分类注释", required = true)
    private String knowledgeSortsRemark;
    @ApiModelProperty(value = "知识点分类排序", required = true)
    private int knowledgeSortsSort;
    @ApiModelProperty(value = "知识点分类状态", required = true)
    private int knowledgeSortsStatus;
}

1.@Api(): 用于类,表示标识这个类是swagger的资源
tags–表示说明
value–也是说明，可以使用tags替代
2. @ApiOperation(): 用于方法,表示一个http请求的操作
value用于方法描述
notes用于提示内容
tags可以重新分组
3. @ApiImplicitParam(): 用于方法，表示单独的请求参数
4. @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
name–参数名称
value–参数说明
dataType–数据类型
paramType–参数类型 – query:请求类型为Json , form :请求为表单类型
example–举例说明
required-是否必须
5. @ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明 (2.2.2版本bug造成example不显示,升级到2.4.0以上即可)
hidden–隐藏
@Api注解可以用来标记当前Controller的功能。
@ApiOperation注解用来标记一个方法的作用。
@ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
• 如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
• 需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略