一、SpringBoot依赖和实例代码准备
本实例基于SpringBoot搭建，所需要的配置和依赖很少，下面添加主要的依赖
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>1.9.6</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>
上面已经添加了相关的依赖，下面构建controller包，应对于项目开发，这里准备俩个不同的controller，其中admin标识后台controller接口，user标识前台应用的controller
其中controller里面的内容如下，注意需要有controller相关注解标注
/** * @Author chenye * @Description **/ @RequestMapping("/admin/user") @RestController public class AdminUserRestController { @GetMapping("/add") public ApiResponse add() { return ApiResponse.ofSuccess("add"); } @GetMapping("/delete") public ApiResponse delete() { return ApiResponse.ofSuccess("delete"); } @GetMapping("/update") public ApiResponse update() { return ApiResponse.ofSuccess("update"); } @GetMapping("/list") public ApiResponse list() { return ApiResponse.ofSuccess("list"); } }
其中ApiResponse就是后端返回前端的响应类Result
二、配置和页面展示
上面已经准备了基本的API接口，下面进行swagger的配置
/** * @Author chenye * @Description **/ @Configuration @EnableSwagger2 @EnableKnife4j @Import(BeanValidatorPluginsConfiguration.class) @ConditionalOnProperty(value = {"knife4j.enable"}, matchIfMissing = true) public class Swagger2Config { /** * 前台API分组 * * @return */ @Bean(value = "indexApi") public Docket indexApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("前台API分组") .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.swagger.user")) .paths(PathSelectors.any()) .build(); } /** * 后台API分组 * * @return */ @Bean(value = "adminApi") public Docket adminApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("后台API分组") .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.swagger.admin")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("swagger-bootstrap-ui RESTful APIs") .description("swagger-bootstrap-ui") .termsOfServiceUrl("http://localhost:8999/") .contact("developer@mail.com") .version("1.0") .build(); } }
上面代码中构建了俩个分组，其中第一个分组主要处理前台部分的API，第二个分组主要处理后台部分的API，apiInfo构建API接口的描述信息
三、测试
swagger-bootstrap-ui默认访问地址是：http://h o s t : {host}:host:{port}/doc.html
四、主要注解
（一）@Api
表示这个类是Swagger的资源，该注解会被Swagger扫描到，该注解可以自定义显示的导航栏标签的名称tag
@RequestMapping("/admin/category") @RestController @Api(value = "商品分类接口", tags = "商品分类接口") public class AdminCategoryRestController { //... }
（二）@ApiOperation
用在方法上，说明方法的作用
@ApiOperation注解中的tags属性做更细粒度的接口分类定义，该注解可以用于多个不同的controller的分组
@RequestMapping("/admin/user") @RestController public class AdminUserRestController { @ApiOperation(value = "添加分类", tags = "商品分类接口") @GetMapping("/add") public ApiResponse add() { return ApiResponse.ofSuccess("add"); } }
上图可以看到在另外的controller中定义的接口方法是可以分属到其他的接口tag下的
（三）@ApiIgnore
忽略掉指定的接口和类，在开发中肯定存在一些用于跳转路由的controller，那么其实这部分是不需要把接口呈现给其他开发人员的，所以就可以通过@ApiIgnore注解忽略掉该注解
@RequestMapping("/admin/user") @RestController @ApiIgnore public class AdminUserRestController { //... }
