swagger,一個API文檔生成工具,當編寫商業項目時,每個項目之間可能需要調用其他項目的API接口,比如說前後端分離項目,這種時候需要寫API文檔,文檔,程序員最討厭自己寫以及別人不寫的一個東西,而Swagger就可以根據在項目中配置的註解自動生成文檔,那麼接下來就開始添加這個小東西
引入jar包
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
添加配置
創建SwaggerConfig配置類
@EnableWebMvc
@EnableSwagger2
@Configuration
public class SwaggerConfig extends WebMvcConfigurationSupport {
/**
* 通過createRestApi函數創建Docket的Bean之後,
* apiInfo()用來創建該Api的基本信息(這些基本信息會展現在文檔頁面中)
* select()函數返回一個ApiSelectorBuilder實例用來控制哪些接口暴露給Swagger來展現,
* apis()函數掃描所有Controller中定義的API, 併產生文檔內容(除了被@ApiIgnore指定的請求)
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// .globalOperationParameters(operationParameters)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
/**
* 創建該Api的基本信息(這些基本信息會展現在文檔頁面中)
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("標題")
.termsOfServiceUrl("http://www.itrip.com/auth")
.contact("[email protected]")
.version("1.0")
.build();
}
}
注意在springMVC配置文件中添加
<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
避免被攔截掉
使用
使用註解在controller類上聲明
@Api(tags = “所在類”) =》 聲明類
@ApiOperation(value = “接口名”,notes = “接口描述”,httpMethod = “發送方式”) = 》 聲明接口
@ApiParam(value = “參數名稱”,name = “參數名”) =》 聲明參數
示例:
@Controller
@Api(tags = "UserController")
public class UserInfoController {
@Autowired
private UserInfoService userInfoService;
@ApiOperation(value = "接口名",notes = "接口描述",httpMethod = "post")
@RequestMapping(value="login",method= RequestMethod.POST)
@ResponseBody
public Dto login(
@RequestParam("userCode")
@ApiParam(value = "參數說明",name = "參數名") String userCode){
ItripUser user = userInfoService.getUserInfo(userCode);
return DtoUtil.returnDataSuccess(user);
}
}
注意在聲明方法的時候最好指明接口訪問當時訪問方式,就是@RequestMapping中method屬性,否則swagger文檔中會把所有請求方式的方法顯示,現的特別雜亂,還有@RequestParam最好也加上,否則swagger上的測試功能可能無法使用
全部做完後重啓項目,訪問:** 項目地址/swagger-ui.html**就好了
常見異常:訪問頁面報404
1、檢查是否配置springMVC靜態資源
2、檢查路徑是否正確