环境:
SpringBoot 2.0.4.RELEASE + Mybatis3.4.6 + Maven3.5.3 + Swagger2.9.2 + Lombok1.18.2
工具:
IDEA
这个项目做了有一段时间了,但是还没有什么大的进展,关于swagger2,使用起来也比较简单,网上有许多教程,我是看书《深入理解Spring Could与微服务构建》这本书,里面简单的介绍了swagger2的使用,然后个人又搜集了一些知识点,进行了补充。
贴代码:
1,swagger配置类。
@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
@Bean
public Docket createRestfulApi() {
ParameterBuilder parameterBuilder = new ParameterBuilder();
parameterBuilder
.parameterType("header") //参数类型支持header, cookie, body, query etc
.name("token") //参数名
.defaultValue("asdf") //默认值
.description("可以不用提供token")
.modelRef(new ModelRef("String"))//指定参数值的类型
.required(false)
.build(); //非必需,这里是全局配置,然而在登陆的时候是不用验证的
List<Parameter> parameterList = new ArrayList<>();
parameterList.add(parameterBuilder.build());
parameterBuilder.parameterType("header")
.name("api-key")
.defaultValue("123")
.description("一定要提供api-key")
.modelRef(new ModelRef("String"))
.required(true)
.build();
parameterList.add(parameterBuilder.build());
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()).globalOperationParameters(parameterList)
.select()
.apis(RequestHandlerSelectors.basePackage("com.ifeng.zlphb.controller"))
.paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("use swagger generate restful api document")
.description("set it up by naison")
.termsOfServiceUrl("")
.version("1.0")
.build();
}
}
2,controller注解
@RestController
@CrossOrigin
@RequestMapping("/")
@Api(value = "关于用户操作的controller",tags = {"包括了很多个接口","其中的token和api-key请谨慎使用"})
public class UserController {
@Autowired
private UserService userService;
@GetMapping("/find/by/{id}")
@ApiOperation(value = "获取用户", notes = "使用ID获取用户")
@ApiImplicitParams(@ApiImplicitParam(name = "id", paramType = "path", dataType = "String", required = true))
public ResponseEntity<?> findById(@PathVariable String id) {
return ResponseEntity.status(HttpStatus.OK).body(userService.findUserById(id));
}
@PostMapping("/register")
@ApiOperation(value = "注册用户", notes = "需要提供用户名和密码")
@ApiImplicitParams({
@ApiImplicitParam(name = "name", paramType = "query", dataType = "String", required = true),
@ApiImplicitParam(name = "password", paramType = "query", dataType = "String", required = true)})
public ResponseEntity<?> findById(@ModelAttribute User user) {
return ResponseEntity.status(HttpStatus.OK).body(userService.register(user));
}