相對于傳統的swager文檔來說,swagger-bootstrap-ui 更具有美化樣式和更适用前端開發人員的接口說明,除此還提供了文檔的增強功能,這些功能是官方swagger-ui所沒有的,每一個增強的功能都是貼合實際,考慮到開發者的實際開發需要,是比不可少的功能,主要包括:
- 個性化配置:通過個性化ui配置項,可自定義UI的相關顯示資訊
- 離線文檔:根據标準規範,生成的線上markdown離線文檔,開發者可以進行拷貝生成markdown接口文檔,通過其他第三方markdown轉換工具轉換成html或pdf,這樣也可以放棄swagger2markdown元件
- 接口排序:自1.8.5後,ui支援了接口排序功能,例如一個注冊功能主要包含了多個步驟,可以根據swagger-bootstrap-ui提供的接口排序規則實作接口的排序,step化接口操作,友善其他開發者進行接口對
SpringBoot接入流程:
1,jar引入
<properties>
<java.version>1.8</java.version>
<swagger.version>2.9.2</swagger.version>
<swagger-bootstrap-ui.version>1.9.6</swagger-bootstrap-ui.version>
</properties>
<!-- 引入swagger-ui包 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${springfox-swagger-ui.version}</version>
</dependency>
<!-- 引入swagger包 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${springfox-swagger-ui.version}</version>
</dependency>
<!-- 引入swagger-bootstrap-ui包 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>${swagger-bootstrap-ui.version}</version>
</dependency>
2.SwaggerConfiguration配置類:
import org.springframework.beans.factory.annotation.Value;
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;
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Value(value = "${server.port}")
private String serverPort;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//掃描端口
.apis(RequestHandlerSelectors.basePackage("com.safe.ecs"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("swagger-bootstrap-ui RESTful APIs")
.description("swagger-bootstrap-ui")
.termsOfServiceUrl("http://127.0.0.1:"+serverPort+"/")
.contact("[email protected]")
.version("1.0")
.build();
}
}
4.接口加入
@RestController
@RequestMapping("/entBaseInfo")
@Api(tags = "企業資訊")
public class EntBaseInfoController {
@ApiOperation(value = "測試接口", notes = "測試接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "keyword", value = "keyword", paramType = "query", dataType = "String")})
@GetMapping("/test")
public void exportEntBaseInfo(@RequestParam(value = "keyword", required = false) String keyword,
HttpServletResponse response) {
List<ExportBaseInfoResp> exportList = null;
//導出數組
DateFormat df1 = new SimpleDateFormat("yyyyMMddHHmmss");
String fileName = "企業清單" + df1.format(new Date());
String titleColumn[] = new String[]{"baseInfoQymc", "baseInfoQyzcdz", "baseInfoFddbrXm", "baseInfoFddbrYddh"};
String titleName[] = new String[]{"企業名稱", "位址", "聯系人", "聯系電話"};
int titleSize[] = new int[]{30, 30, 15, 15};
//執行導出
ExportExcelUtil.writeExcel(response, fileName, titleColumn, titleName, titleSize, exportList);
}
}
效果如下:http://127.0.0.1:8888/ecs/doc.html(由于我這裡配置了項目位址是以需要加上 /ecs)
此外 @ApiModel("企業資訊添加請求類") @ApiModelProperty(value = "位址") 這兩個注解還可以用在 請求參數或相應參數的的實體類上: