springmvc和swagger2
<!--restfull APi swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
apiInfoBuilder.title("swagger2");
apiInfoBuilder.description("swagger2文档");
apiInfoBuilder.contact(new Contact("xxx", "https://www.xxxx.com/", ""));
apiInfoBuilder.version("2.0");
return apiInfoBuilder.build();
}
}
剩下的就是Restful服务上,使用注解了
@Api(description = “用户管理”) //用在类上,比如Controller
@ApiOperation(value = “获取所有用户列表”) //用在方法上,说明方法的作用
@ApiParam(value = “用户ID”) String userId //用在参数上,说明参数的作用 还有@ApiImplicitParam
@RestController
@Api(description = "用户管理")
public class UserRestController extends BaseController {
@Autowired
private SysUserService sysUserService;
@GetMapping("r/user/get")
@ApiOperation(value = "获取特定用户详情")
public Object getUser(ModelMap modelMap, @ApiParam(value = "用户ID") String userId) {
}
@PostMapping("r/user/add")
@ApiOperation(value = "添加用户")
public Object addUser(ModelMap modelMap, @ModelAttribute @Valid SysUser user, BindingResult result) {
}
}
这些方法已经基本足够了。但是还有一些参数比如HttpServletRequest、HttpServletResponse、HttpSession、ModelMap 这些参数在生成 API 文档时是无意义的,Swagger 正确的配置方式?
刚开始时使用 @ApiParam(hidden = true) 注解这些参数,方法繁多的时候,这些类型的入参都要写一遍,使用起来很冗余。
在 API 中发现 Docket 对象有 ignoredParameterTypes 方法,在配置类中统一定义忽略的参数类型即可,这样就方便很多。
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.ignoredParameterTypes(ModelMap.class, HttpServletRequest.class,HttpServletResponse.class, BindingResult.class)
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
请求的参数为对象时,使用Spring @ModelAttribute 注解对应对象,对象当中的属性使用 @ApiModelProperty ,屏蔽莫个属性 @ApiModelProperty(hidden = true)
@ApiModelProperty(hidden = true)
private String uuid;
@ApiModelProperty("姓名")
private String name;