Swagger2

最新推荐文章于 2024-07-04 09:05:13 发布

好的好的，你是对的

最新推荐文章于 2024-07-04 09:05:13 发布

阅读量127

点赞数

本文链接：https://blog.csdn.net/qq_45853150/article/details/118198569

版权

Swagger2

Swagger2 简介

在前后端分离开发中，为了减少与其他团队的沟通成本，一般构建一份 RESTful API 文档来描述所有的接口信息，但是这样的做法有很大的弊端

接口众多
维护不方便，一单接口发生变化，就要修改文档
测试不方便，一般只能借助第三方工具来测试。（postman）

Swagger2 是一个开软软件框架，可以帮助开发人员设计、构建、记录和使用 RESTful Web 服务，他将代码和文档融为一体，可以完美解决上面描述的问题，是大部分精力集中到业务中去。

Swagger2 可以非常轻松的整合到 Spring Boot 项目中。

整合Spring Boot

首先创建 Spring Boot Web 项目，添加 Swagger2相关依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

接下来创建Swagger2 的配置类

@Configuration
@EnableSwagger2
@Profile({"dev", "debug"})
public class SwaggerConfig {
	
	/**
     * 访问地址：http://ip:port/swagger-ui.html
     * @return
     */

    @Bean
    public Docket adminApi() {
        return new Docket(DocumentationType.SWAGGER_2)
        		.select()
                .apis(RequestHandlerSelectors.basePackage("com.r*z.o2o"))
//                .paths(PathSelectors.regex("/admin.*"))
                .groupName(SystemConstant.BACKGROUND_BUSINESS_INTERFACE)
                .apiInfo(apiInfo(SystemConstant.BACKGROUND_BUSINESS_INTERFACE, "1.0"))
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                
                .build().protocols(Stream.of("http").collect(Collectors.toSet()));
    }

    
    private ApiInfo apiInfo(String title, String version) {
        return new ApiInfoBuilder()
                .title(title)
                .version(version)
                .build();
    }
}

代码解释：

首先通过@EnableSwagger2 注解开启 Swagger2，然后最主要的是配置一个 Docket
通过 apis方法配置要扫描的 controller 的位置，通过 paths 方法配置路径。
在 apiInfo 中构建文档的基本信息，例如描述，联系人信息、版本、标题等。

配置好后就可以开发接口了：

@RestController
@RequestMapping("${adminPath}/order/base")
@Api(tags = "admin端订单管理")
public class OrderController extends BaseController {
	
	@PostMapping(value = "list", consumes = "application/json;charset=UTF-8")
    @ApiOperation(value = "订单列表")
    public ApiResponse list(@RequestBody JSONObject params) {
	......
	}
}

@ApiModel(value = "Order对象", description = "订单表")
public class Order extends Entity {
    
    @ApiModelProperty(value = "订单ID")
    @TableId(value = "order_id")
    private Integer orderId;
}