SpringBoot+Swagger配置及注解详解
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
