Springboot 整合swagger-ui

Springboot 整合swagger-ui

JSON API documentation for spring based applications

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

一、添加依赖

<!--目前依赖的最高版本是2.9.2-->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.2.2</version>
</dependency>

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

二、编写配置类

package top.xtslife.mall.config;

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;

/**
 * swagger2文档的配置
 * @Author 小涛
 * @Create 2019-08-09  22:02
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("top.xtslife.mall.controller"))
                // 为有@Api注解的controller生成文档
                // .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                // 为有@ApiOperation注解的方法生成API文档
            //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("SwaggerUI 演示")
                .description("mall-crud")
                .contact("xtslife")
                .version("1.0")
                .build();
    }
}

三、使用注解

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

四、示例

@Api(tags = "PmsBrandController", description = "商品品牌管理")
@RestController
@RequestMapping("/brand")
public class PmsBrandController {
    
    @Autowired
    private PmsBrandService pmsBrandServiceImpl;

    @ApiOperation("获取所有商品列表")
    @GetMapping("/listAll")
    public CommonResult<List<PmsBrand>> getBrandList(){
        return CommonResult.success(pmsBrandServiceImpl.listAllBrand());
    }
}

五、接口文档的URL

localhost:8080/swagger-ui.html
注：一定记得要输上后缀html
   在接口文档中可以直接对接口进行测试（类似于postMan的使用)