SpringBoot使用Swagger创建在线接口文档
一、介绍
可以访问一下这个
Spring Boot整合swagger使用教程 - 随风行云 - 博客园 (cnblogs.com)
Swagger 是为了方便用户在创建一个接口时,自动创建一个接口文档。
优点:
自动生成文档,只需要在接口中使用注解进行标注(@ApiModel @ApiParam)
自动更新文档,当接口被修改,文档也会自动对应修改
支持在线进行调试。
缺点:
不能创建测试用例,如果需要对测试用例,可以使用postman。
规范问题
没有接口文档的更新管理,一个接口更新之后,可能不关心旧版的接口信息。
二、步骤:
2.1 在maven中添加依赖:
<!-- swagger--> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
2.2 进行swagger的配置
package com.qiang.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * @author * @ClassName SwaggerConfig * @description: 在线配置文档类 * @dtetime 2023年 06月 27日 15:55 * @version: 1.0 */ @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi(){ return new Docket(DocumentationType.SWAGGER_2). pathMapping("/").select(). apis(RequestHandlerSelectors.basePackage("com.qiang")). paths(PathSelectors.any()). build().apiInfo(new ApiInfoBuilder().title("SpringBoot整合Swagger"). description("上班拿去用吧"). version("1.0"). contact(new Contact("qiang","http://www.qiang.com","forhappiness19@163.com")) .license("The Apache license"). licenseUrl("http://www.qiang.com").build()); } }
2.3 进行控制器(模拟接口)的配置
@RestController @Api(tags = "这是一个swagger的一个简单的项目组") public class SwaggerController { @GetMapping("/get") @ApiOperation(value = "第一个测试" ,notes = "第一个测试的note") public String get(){ return "aaa"; } @GetMapping("/list") @ApiOperation(value = "第二个测试" ,notes = "第二个测试的note") public String list(String id){ return "第二个测试 "+id; } }
2.4访问http://localhost:端口号/swagger-ui.html
三。常用注解:
@Api: 用于类,标识这个类是swagger的资源
@ApiIgnore: 用于类,忽略该 Controller,指不对当前类做扫描
@ApiOperation: 用于方法,描述 Controller类中的 method接口
@ApiParam: 用于参数,单个参数描述,与 @ApiImplicitParam不同的是,他是写在参数左侧的。如( @ApiParam(name="username",value="用户名")Stringusername)
@ApiModel: 用于类,表示对类进行说明,用于参数用实体类接收
@ApiProperty:用于方法,字段,表示对model属性的说明或者数据操作更改
@ApiImplicitParam: 用于方法,表示单独的请求参数
@ApiImplicitParams: 用于方法,包含多个 @ApiImplicitParam
@ApiResponse: 用于方法,描述单个出参信息
@ApiResponses: 用于方法,包含多个@ApiResponse
@ApiError: 用于方法,接口错误所返回的信息