使用Swagger2生成API文档
作者:互联网
Swagger2是一个开源软件框架,由大型工具生态系统支持,可帮助开发人员设计,构建,记录和使用Restful Web服务。
这是“维基百科”上对于Swagger2的一个介绍,可见Swagger2是属于第三方框架,对标的是Restful风格的API,使用Swagger2生成API文档,避免了传统手工记录的繁琐,也便于保存、整理、查阅和调试API接口。
#####在SpringBoot项目中引入Swagger2:
- pom.xml引入对应的依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
- 增加SwaggerConfig.java配置文件,在Applcation.java中添加@EnableSwagger2,项目启动时同时加载swagger2
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//加了ApiOperation注解的类,生成接口文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//接口对应包下的类,生成API文档
.apis(RequestHandlerSelectors.basePackage("io.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("可读小说")
.description("后台管理系统API文档")
.termsOfServiceUrl("https://swagger.io/")
.version("1.0.1")
.build();
}
}
同时利用Swagger2提供的注解对接口进行说明,通过访问http://localhost:8080/swagger-ui.html便可获取到相关API文档。
#####注解的使用(demo)
@Api(tags="小说信息接口")
@RestController
@RequestMapping("/info")
public class InfoController {
@ApiOperation("添加小说信息")
@PutMapping("/add")
private String addInfo(){
return "success";
}
@ApiOperation("获取小说信息")
@GetMapping("/{id}")
private String getInfo( @ApiParam("小说id") @PathVariable("id")int id){
return "info" + id;
}
}
最后再说说Swagger2的常用注解:
- @Api:用于类,表示标识这个类是swagger的资源
- @ApiOperation:用于方法,表示一个http请求的操作
- @ApiParam:用于方法,参数,字段说明,表示对参数的添加元数据(说明或是否必填等)
- @ApiModel:用于类,表示对数据模型进行说明,用于参数用实体类接收
- @ApiModelProperty:用于方法,字段,表示对model属性的说明
- @ApiIgnore:用于类,方法,方法参数,对应的将不会被显示到文档里
- @ApiImplicitParam:用于方法,作用于非对象参数集
- @ApiImplicitParams:用于方法,包含多个 @ApiImplicitParam
标签:Swagger2,ApiOperation,API,文档,swagger,id 来源: https://blog.csdn.net/hsf15768615284/article/details/90631996