SpringBoot集成Swagger-UI
1.添加必要的依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
注意:尽量使用较新的版本,因为在实际开发过程中,有些api文档中的一些细节控制低版本不支持,比如控制一个实体属性在api文档上不展示。
2.编写对应Swagger的配置类
package com.tufire.seller.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* Swagger配置类,为所有的controller生成访问的API文档
* 本地访问地址:http://localhost:{server.port}/swagger-ui.html
*
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
private static final String CONTROLLER_PACKAGE = "控制层根目录";
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).groupName("API名称描述").apiInfo(apiInfo()).select()
.apis(RequestHandlerSelectors.basePackage(CONTROLLER_PACKAGE)).paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("API名称描述").contact(new Contact("", "", "联系人邮箱地址")).version("1.0").build();
}
}
3.控制层进行定义API接口的各种描述
package com.tufire.seller.api.user;
import com.tufire.common.util.ObjectUtil;
import com.tufire.common.util.Result;
import com.tufire.seller.api.basic.BasicApi;
import com.tufire.seller.query.user.DistrictQuery;
import com.tufire.user.client.DistrictClient;
import com.tufire.user.dto.DistrictDto;
import com.tufire.user.vo.commmon.DistrictVo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
@Api(value = "地区相关接口", tags = "地区相关接口")
@RestController
@RequestMapping("/authc/district/")
@Slf4j
public class DistrictApi extends BasicApi {
@Autowired
private DistrictClient districtClient;
@ApiOperation(value = "获取地区信息列表", notes = "获取地区信息列表",produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@RequestMapping(value = "find_list",method = RequestMethod.POST)
public Result<List<DistrictVo>> findList(@ModelAttribute DistrictQuery query){
DistrictDto districtDto = ObjectUtil.source2Target(query, DistrictDto.class);
return Result.generateSuccess(districtClient.findList(districtDto));
}
}
4.访问自己的API接口文档
http://localhost:8092/swagger-ui.html#/
5.API通常的界面风格就如上面的效果,有没有更好的界面展示风格呢,答案是肯定的!
在原有项目的基础上增加如下依赖:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.8.7</version>
</dependency>
现在访问如下地址:
http://localhost:8092/doc.html
第4和第5两种方式是兼容的,仅仅是UI展示效果不同。