SpringBoot 使用 swagger 實現Rest Api 文件化
阿新 • • 發佈:2018-11-19
swagger 允許使用者在一個html5 web 頁面中,對API 進行文件化和互動
優點:
功能豐富 :支援多種註解,自動生成介面文件介面,支援在介面測試API介面功能;
及時更新 :開發過程中花一點寫註釋的時間,就可以及時的更新API文件,省心省力;
整合簡單 :通過新增pom依賴和簡單配置,內嵌於應用中就可同時釋出API介面文件介面,不需要部署獨立服務。
實現 swagger 文件
- 新增依賴
主要是 新增 swagger2 核心包 以及 swagger-ui介面包 的依賴
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency>
- 配置 api 頁面的基本資訊
/** * Created by Sean on 2018/10/10 *Api 文件頁面 基本資訊 * 可以通過註解注入相關配置。 * 通過這些配置可以指定在spring-boot啟動時掃描哪些controller層的資料夾, * 另外可以指定API文件頁的標題和描述資訊等內容 * @author Sean */ @Configuration @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.voicecyber")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo(){ return new ApiInfoBuilder() .title(" RESTful APIs") .description(" Rest Server api介面文件") .version("1.0") .build(); } }
- 將swagger-ui 暴露到spring boot環境 主要是配置spring mvc 的一些資源攔截
/** * Created by Sean on 2018/10/10 *將swagger-ui中的介面配置至spring-boot環境 * @author Sean */ @Component public class WebMvcConfig extends WebMvcConfigurerAdapter { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/js/**").addResourceLocations("classpath:/js/"); registry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } }
- 在controller 中編寫自己的api 文件 主要在於引數,和介面的描述
@Api(value = "RestApi", description = "Rest Api Server")
@RestController
@RequestMapping("api")
public class RestApiController {
/**
*需要注意的是 必須指定 RequestMethod 的具體型別,不然前端會顯示多種型別的Rest
*/
@ApiOperation(value = "資訊總覽", notes = "使用者資訊總覽")
@ApiImplicitParam(name = "type", value = "獲取資訊的型別(name ,sex)", paramType = "query", dataType = "string")
@RequestMapping(value = "info", method = RequestMethod.GET)
@ResponseBody
public ResponseEntity getUserInfo(String type) {
System.out.println(type);
return new ResponseEntity("this is user info ", HttpStatus.OK);
}
}
- .配置properties 檔案
這個檔案配置非常重要 ,主要在於
springfox.documentation.swagger.v2.host 的配置非常重要,在訪問的swagger-ui.html 頁面時。如果訪問的路徑不統一,那麼可能會發生跨域的問題
springfox.documentation.swagger.v2.host=127.0.0.1:8080
springfox.documentation.swagger.v2.path=/api
server.port=8080
server.context-path=/rest
- 訪問頁面
使用上面的host 路徑 再加上 swagger-ui.html 即可訪問頁面http://127.0.0.1:8080/swagger-ui.html
github url:springbootrestswagger