Springboot2.x整合Swagger3.x
作者:互联网
1、SpringBoot添加pom文件依赖
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.4.11</version> <relativePath/> </parent> <properties> <java.version>11</java.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!--swagger3依赖--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>1.18.16</version> <scope>provided</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build>
2、配置文件增加配置
server: port: 8082 spring: application: name: swagger-server swagger: enable: true application-name: ${spring.application.name} application-version: 1.0 application-description: 电商平台管理后端接口文档
3、创建配置类
import io.swagger.annotations.ApiOperation; import lombok.Data; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.context.annotation.Bean; import org.springframework.stereotype.Component; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.oas.annotations.EnableOpenApi; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.ApiKey; import springfox.documentation.service.Contact; import springfox.documentation.service.SecurityScheme; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import java.util.ArrayList; import java.util.List; @Component @EnableOpenApi @ConfigurationProperties("swagger") @Data public class SwaggerConfiguration { /** * 是否开启swagger,生产环境一般关闭,所以这里定义一个变量 */ private Boolean enable; /** * 项目应用名 */ private String applicationName; /** * 项目版本信息 */ private String applicationVersion; /** * 项目描述信息 */ private String applicationDescription; @Bean public Docket docket() { return new Docket(DocumentationType.OAS_30) .pathMapping("/") // 定义是否开启swagger,false为关闭,可以通过变量控制,线上关闭 .enable(enable) //配置api文档元信息 .apiInfo(apiInfo()) // 选择哪些接口作为swagger的doc发布 .select() //apis() 控制哪些接口暴露给swagger, // RequestHandlerSelectors.any() 所有都暴露 // RequestHandlerSelectors.basePackage("net.xdclass.*") 指定包位置 // withMethodAnnotation(ApiOperation.class)标记有这个注解 ApiOperation .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .paths(PathSelectors.any()).build() // 如何保护我们的Api,有三种验证(ApiKey, BasicAuth, OAuth) .securitySchemes(security()) // 接口文档的基本信息 .apiInfo(apiInfo()); } /** * 接口文档详细信息 * * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title(applicationName) .description(applicationDescription) .contact(new Contact("联系标题", "https://www.baidu.com", "510716143@qq.com")) .version(applicationVersion) .build(); } private List<SecurityScheme> security() { ArrayList<SecurityScheme> apiKeys = new ArrayList<>(); apiKeys.add(new ApiKey("accessToken", "accessToken", "accessToken")); return apiKeys; } }
4、创建controller类
import com.example.model.User; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import io.swagger.v3.oas.annotations.responses.ApiResponse; import io.swagger.v3.oas.annotations.responses.ApiResponses; import org.springframework.web.bind.annotation.*; import java.util.ArrayList; import java.util.List; @Api(tags = "测试接口") @RestController @RequestMapping("demo") public class DemoController { @ApiOperation("查询集合数据") @ApiImplicitParams(value = { @ApiImplicitParam(name = "id",value = "查询id"), @ApiImplicitParam(name = "name",value = "查询名称",required = true) }) @ApiResponses({ @ApiResponse(responseCode = "200", description ="OK"), @ApiResponse(responseCode = "204", description ="No results returned") }) @PostMapping("list1") public List<String> list1(Integer id,String name){ List<String> list = new ArrayList<>(); list.add("张三"); list.add("李四"); return list; } @ApiOperation("测试删除") @ApiImplicitParam(name = "id", value = "删除ID", example = "100", required = true) @PostMapping(value = "/delete/{id}") public Integer delete(@PathVariable("id") Long id){ System.out.println("删除成功:"+id); return 200; } @ApiOperation("保持对象") @PostMapping("save") public Object save(@RequestBody User user){ User user1 = new User(); user1.setId(user.getId()); user1.setName(user.getName()); return user1; } }
5、访问 http://localhost:8082/swagger-ui/index.html
6、常用注解,官网
- @Api()用于类;
表示标识这个类是swagger的资源
- @ApiOperation()用于方法;
表示一个http请求的操作
- @ApiParam()用于方法,参数,字段说明;
表示对参数的添加元数据(说明或是否必填等)
- @ApiModel()用于类
表示对类进行说明,用于参数用实体类接收
- @ApiModelProperty()用于方法,字段
表示对model属性的说明或者数据操作更改
- @ApiIgnore()用于类,方法,方法参数
表示这个方法或者类被忽略
- @ApiImplicitParam() 用于方法
表示单独的请求参数
- @ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
具体使用举例说明:
@Api()
用于类;表示标识这个类是swagger的资源
tags–表示说明
value–也是说明,可以使用tags替代
标签:swagger,ApiOperation,documentation,Swagger3,Springboot2,整合,import,springfox,name 来源: https://www.cnblogs.com/M87-A/p/15363834.html