swagger配置及注解詳解
1.加入依賴的jar包
<!--引入swagger的依賴--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
2.配置swagger配置文件
package com.jt.config; import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import com.google.common.base.Predicates; import io.swagger.annotations.ApiOperation; 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; /** * Swagger2的接口配置 * 在與spring boot集成時,放在與Application.java同級的目錄下。 * 通過@Configuration注解,讓Spring來加載該類配置。 * 再通過@EnableSwagger2注解來啟用Swagger2。 * @author DragonBai * */ @Configuration @EnableSwagger2 @ConditionalOnExpression("${swagger.enable}") //開啟訪問接口文檔的權限 public class SwaggerConfig { /** * 創建API */ @Bean public Docket createRestApi() { return new Docket( DocumentationType.SWAGGER_2 ) // 用來創建該API的基本信息,展示在文檔的頁面中(自定義展示的信息) .apiInfo( apiInfo() ) // 設置哪些接口暴露給Swagger展示 .select() // (第一種方式)掃描所有有注解的api,用這種方式更靈活 .apis( RequestHandlerSelectors.withMethodAnnotation( ApiOperation.class ) ) // (第二種方式)掃描指定包中的swagger注解 //.apis(RequestHandlerSelectors.basePackage("com.hubiao.pay.merchant.controller")) // (第三種方式)掃描所有 //.apis(RequestHandlerSelectors.any()) .paths( PathSelectors.any() ) //(第四種方式)只顯示api路徑下的頁面 //.paths(Predicates.and(PathSelectors.regex("/api/.*"))) .build(); } /** * 添加摘要信息 * 創建該API的基本信息(這些基本信息會展現在文檔頁面中) * 訪問地址:http://項目實際地址/swagger-ui.html */ private ApiInfo apiInfo() { // 用ApiInfoBuilder進行定制 return new ApiInfoBuilder() // 設置標題 .title( "標題:商戶應用API文檔" ) // 描述 .description( "描述:向前端提供商戶應用的ResultFul風格接口文檔" ) // 作者信息 //.contact( "hubiao" ) .contact(new Contact("DragonBai", "http://www.DragonBai.cn", "z591593455@qq.com")) // 版本 .version( "版本號:" + "V1.0.0" ) .build(); } }
3.生成swagger文檔
package com.jt.controller; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RestController; import com.jt.pojo.Users; import com.jt.server.UserService; import com.jt.util.JsonResult; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import lombok.extern.slf4j.Slf4j; /** * Swagger使用的注解及其說明: @Api:用在類上,說明該類的作用。 @ApiOperation:注解來給API增加方法說明。
@ApiParam:用對象來接收參數
public ResponseEntity<Merchant> merchantAdd(@RequestBody @ApiParam(name="第一個參數", value = "Merchant", required = true) Merchant merchant)
@ApiImplicitParams : 用在方法上包含一組參數說明。 @ApiImplicitParam:用來注解來給方法入參增加說明。 @ApiResponses:用於表示一組響應 @ApiResponse:用在@ApiResponses中,一般用於表達一個錯誤的響應信息 l code:數字,例如400 2 message:信息,例如"請求參數沒填好" 3 response:拋出異常的類 例:方法返回void時 @ApiResponses(value = { @ApiResponse(code = 1, message = "當http狀態碼為200,且返回code=ok時,data集合中的對象結構", response = PersonResponse.class) }) @ApiModel:描述一個Model的信息(一般用在請求參數無法使用@ApiImplicitParam注解進行描述的時候) l @ApiModelProperty:描述一個model的屬性 例:接收對象傳參的例子在POJO上增加 //@ApiModel(value="醫生對象模型") //public class DemoDoctor{ // @ApiModelProperty(value="id" ,required=true) // private Integer id; // @ApiModelProperty(value="醫生姓名" ,required=true) // private String name;} 在后台采用對象接收參數時,Swagger自帶的工具采用的是JSON傳參, 測試時需要在參數上加入@RequestBody * @author DragonBai * */ @Slf4j @RestController //用在類上,說明該類的作用。 @RequestMapping("/api") @Api(value = "商戶平台應用接口",tags = "用戶操作接口") public class UserSWController {//http://localhost:8090/swagger-ui.html#/ @Autowired private UserService userService; /** * @ApiImplicitParam的參數說明: * paramType:指定參數放在哪個地方: *1.header:請求參數放置於Request Header,使用@RequestHeader獲取 2.query:請求參數放置於請求地址,使用@RequestParam獲取 3.path:(用於restful接口)-->請求參數的獲取:@PathVariable 4.body:請求參數放置body @RequestBody 5.form:請求參數放置form表單序列化(不常用) *name:參數名 *dataType:參數類型 int string long 小寫 *required:參數是否必須傳 true | false *value:說明參數的意思 *defaultValue:參數的默認值 * * @param userId * @return */ @ApiOperation(value="根據用戶編號獲取用戶信息",httpMethod = "GET", notes="test: 僅1和2有正確返回") @ApiImplicitParam(paramType="path", name = "userId", value = "用戶ID", required = true, dataType = "int",example = "7") //@GetMapping("/{userId}")//不能使用否則,訪問不了頁面 @RequestMapping(value = "/{userId}",method =RequestMethod.GET) public JsonResult<Users> getUser(@PathVariable Integer userId) { log.info("get user, userId="+userId); Users u = userService.getUser(userId); return JsonResult.ok(u); } @ApiOperation(value = "添加用戶積分",httpMethod = "GET") @ApiImplicitParams({ @ApiImplicitParam(paramType="path", name = "userId", value = "用戶ID", required = true, dataType = "int",example = "7"), @ApiImplicitParam(paramType="query", name = "score", value = "用戶積分", required = true, dataType = "int",example = "100") }) //@GetMapping("/{userId}/score") @RequestMapping(value = "/{userId}/score",method =RequestMethod.GET) public JsonResult addScore(@PathVariable Integer userId, Integer score) { userService.addScore(userId, score); return JsonResult.ok(); } }
問題:找不到html頁面可能是參數類型對應swagger錯誤,也可能是靜態資源加載過濾
paramType會直接影響程序的運行期,如果paramType與方法參數獲取使用的注解不一致,會直接影響到參數的接收
dataType類型要對應正確,否則swagger測試無法輸入參數報紅框,后台沒有反應
Conntroller中定義的方法必須在@RequestMapper中顯示的指定RequestMethod類型,否則SawggerUi會默認為全類型皆可訪問, API列表中會生成多條項目
1.//@GetMapping("/{userId}")//不能使用否則,訪問不了頁面,@GetMapping("/{id}"), 正好與測試頁面的網址相互沖突,去掉“/”
2.過濾設置,不搬沒錯不用
3.在使用@ApiModelProperty注解在字段上時,如果字段的類型為Long或是int類型,那么程序啟動后,訪問swagger-ui.html的頁面,程序會報錯
#java.lang.NumberFormatException: For input string: ""
解決:yml
#添加日志輸出
logging:
level:
com.jt.mapper: debug
io.swagger.models.parameters.AbstractSerializableParameter: error
或者@ApiImplicitParam加上example
@ApiImplicitParam(paramType="path", name = "userid", value = "用戶ID", required = true, dataType = "int",example = "7")
//package com.jt.config; // //import org.springframework.context.annotation.Configuration; //import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; //import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter; // //@Configuration //public class WebMvcConfig extends WebMvcConfigurerAdapter { // @Override // public void addResourceHandlers(ResourceHandlerRegistry registry) { // //在配置靜態資源時捕獲swagger-ui.html映射到"classpath:/META-INF/resources/" //// registry.addResourceHandler("swagger-ui.html") //// .addResourceLocations("classpath:/META-INF/resources/"); // // registry.addResourceHandler("/**").addResourceLocations("classpath:/static/"); // registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); // // registry.addResourceHandler("/templates/**") // .addResourceLocations("classpath:/META-INF/resources/templates/"); // } //} //
https://blog.csdn.net/sanyaoxu_2/article/details/80555328
https://blog.csdn.net/wyb880501/article/details/79576784