SpringBoot整合Swagger

SpringBoot整合Swagger

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

 

简介：Swagger™的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。

 

实例：springBoot集成Swagger2，构建优雅的Resetful API

 

一：引入依赖（pom.xml）：

 <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger2</artifactId>

            <version>2.4.0</version>

        </dependency>

 

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger-ui</artifactId>

            <version>2.4.0</version>

        </dependency>  

 

二：创建Swagger2配置文件

@Configuration    //声明该类为一个配置类

@EnableSwagger2   //开启Swagger2

publicclassSwagger2Config {

    @Bean

    public Docket createRestApi() {

        returnnewDocket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .select()

               .apis(RequestHandlerSelectors.basePackage("扫描的Controller包"))  //apis()指定扫描的包生成文档

                .paths(PathSelectors.any())

                .build();

    }

    private ApiInfo apiInfo() {

        returnnew ApiInfoBuilder()

                .title("springboot利用swagger构建api文档")

                .description("介绍")

                .termsOfServiceUrl("url")

                .version("1.0")

                .build();//启动工程访问：http：//ip:port/swagger-ui.thml

 

    } 

} 

 

 

 

常用注解的使用：

@Configuration ：配置类注解，写在配置类名上面，功能是声明该类为一个配置类

@EnableSwagger2： 开启Swagger2，写在Swagger配置类，类名上方

 

@Api :写在controller类上方，用来标注该类具体实现内容

常用属性有：

         Value:介绍该api

                   tags：可以使用tags()允许你为操作设置多个标签的属性，而不是使用该属性

                   description：可描述该类的作用

 

@ApiOperation: 作用在方法上，表示一个http请求的操作

         常用属性：

                   Value：用于方法描述

                   Notes:用于提示内容

                  

@ApiImplicitParam:作用在方法上，对请求参数的介绍

         常用属性：

                   Name:值为参数名

                   Value：参数的描述

                   Required：参数是否必输

                   dataType：参数类型

                   paramType::查询参数类型