一、简介
-
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
-
在 WEB 开发中不可否认的是我们需要给客户端提供 API 接口，这个时候需要借助 postman、rap 等工具 进行调试，以便于接口能正常交付给客户端人员，用过其它工具的应该知道一个 POST 请求一堆参数是非常枯燥且烦人的事情，而 swagger 就是让你摆脱这种束缚感
作用：
- 接口的文档在线自动生成。
- 功能测试。
Swagger是一组开源项目，其中主要要项目如下： - Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
- Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。
- Swagger-js: 用于JavaScript的Swagger实现。
- Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
- Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
- Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。
二、使用
1、gradle导入依赖
compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
2、写配置类
@EnableSwagger2
@Configuration
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
// 一些接口文档信息的简介
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("spring Boot 中构建RESTful API")
.termsOfServiceUrl("")
.version("1.0")
.build();
}
}
@SuppressWarnings("deprecation")
@Configuration
public class SwaggerWebMVCConfig extends WebMvcConfigurerAdapter {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
3、在启动类添加注解
Springboot 1.X 版本需要在启动类添加 @EnableSwagger2Doc 但是 2.X 版本后无需添加
@EnableSwagger2
@SpringBootApplication
public class YoPointServerApplication {
public static void main(String[] args) {
SpringApplication.run(YoPointServerApplication.class, args);
}
}
4、配置
1、在application.yml中添加
spring:
swagger:
enabled: true
2、或在application.properties中添加
spring.swagger.enabled=true
spring.swagger.enabled：提供该配置目的是方便多环境关闭，一般生产环境中不会暴露它
5、写生产文档的注解
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
- @Api：修饰整个类，描述Controller的作用
- @ApiOperation：描述一个类的一个方法，或者说一个接口
- @ApiParam：单个参数描述
- @ApiModel：用对象来接收参数
- @ApiProperty：用对象接收参数时，描述对象的一个字段
- @ApiResponse：HTTP响应其中1个描述
- @ApiResponses：HTTP响应整体描述
- @ApiIgnore：使用该注解忽略这个API
- @ApiError ：发生错误返回的信息
- @ApiParamImplicitL：一个请求参数
- @ApiParamsImplicit 多个请求参数
@Api(tags = "1.1", description = "角色管理", value = "角色管理")
@RestController
@RequestMapping(value = "/role")
public class RoleController extends CorsConfig {
@Autowired
IRoleService rolesServiceImp;
@ApiOperation("新增商户角色信息")
@PostMapping
public void add(@RequestBody RoleEditVo roleEditVo) {
rolesServiceImp.add(roleEditVo);
}
@ApiOperation("修改商户角色信息")
@PutMapping
public void update(@RequestBody RoleEditVo roleEditVo) {
rolesServiceImp.update(roleEditVo);
}
@ApiOperation("通过ID删除一条商户角色数据")
@DeleteMapping("/{id}")
public void delete(@PathVariable String id) {
rolesServiceImp.delete(id);
}
@ApiOperation("批量删除商户角色数据")
@DeleteMapping
public void delete(@RequestBody IdListVo idListVo) {
rolesServiceImp.delete(idListVo);
}
}
6、浏览器访问
http://localhost:8080/swagger-ui.html
图一
网友评论