SpringBoot整合Swagger2搭建在线api接口文档

最新推荐文章于 2024-10-07 11:22:30 发布

彭于晏啊啊啊啊啊啊啊

最新推荐文章于 2024-10-07 11:22:30 发布

阅读量260

点赞数

本文链接：https://blog.csdn.net/weixin_42622769/article/details/108158670

版权

认识Swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用：接口的文档在线自动生成；功能测试。

说白了就是：1.实时更新API文档 2.提供功能测试（post方法不用再使用postman测试了，这个还是非常方便的）

Swagger 集成文档具有以下几个优势

功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

如何使用Swagger

1.在pom.xml里面添加swagger 的maven依赖

	 <!--Swagger2相关的依赖-->
        <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>

2.添加Swagger的配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    // swagger开关，开发环境开启，生产环境关闭
    @Value("${swagger.enabled}")
    private boolean enableSwagger;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                .enable(enableSwagger)
                .select()
                //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                .apis(RequestHandlerSelectors.basePackage("com.springswagger.controller"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * @Description swagger基本信息
     * @Param
     * @return 
     * @Author zhen.ma
     * @Date 2020.06.11 22:26
     **/
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题(API名称)
                .title("SpringBoot使用Swagger2构建restful Api文档")
                //文档描述
                .description("接口说明")
                //服务条款URL
                .termsOfServiceUrl("http://127.0.0.1:8080/")
                //联系信息
                .contact(new Contact("xiao.ge","http://xiao.ge.com","3311247943@qq.com"))
                //版本号
                .version("V1.0")
                .build();
    }

	//swagger接口文档界面
    //http://localhost:8080/swagger-ui.html
}

3.添加测试类控制器

@RestController
@RequestMapping("api/v1")
@Api(value = "测试接口", tags = "UserController", description = "测试接口相关")
public class MyController {

    @GetMapping("/")
    @ApiOperation(value = "访问网站首页", notes = "网站首页")
    public void index() {

    }

    @GetMapping(value = "/mi", produces = "application/json")
    @ApiImplicitParam(name = "num", value = "数字", required = true, dataType = "int", paramType = "query")
    @ApiOperation(value = "一个数的平方", notes = "求一个数的平方")
    public int getNum2(@RequestParam int num) {
        return num*num;
    }
}