Swagger简介和使用

1. Swagger介绍

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

作用：

1. 接口的文档在线自动生成。
2. 功能测试。

Swagger是一组开源项目，其中主要要项目如下：

1. Swagger-tools: 提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
2. Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。
3. Swagger-js: 用于JavaScript的Swagger实现。
4. Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
5. Swagger-ui： 一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
6. Swagger-codegen： 一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

2. Maven导入依赖

版本号请根据实际情况自行更改。

<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>

3. 创建Swagger配置类

package com.test.swagger.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.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
/**
 * Swagger2配置类
 * 在与SpringBoot集成时,通过@Configuration注解,让Spring来加载该类配置.
 * 再通过@EnableSwagger2注解来启用Swagger2.
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    
    /**
     * 配置Swagger Docket的bean实例
     */
    @Bean
    public Docket docket() {
		/*
		* 设置Swagger在生产环境中使用，在发布..环境不使用
		*/
		//设置要显示 Swagger环境
		Profiles profiles = Profiles.of("dev");
		//通过environment.acceptsProfiles判断是否处在自己设置的环境中
		boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //配置Api文档的分组  ??? 如何配置多个分组, 配置多个Docket实例即可 
                .groupName("xxxx")
                .enable(flag) // enable 指是否启动Swagger，为false 则Swagger不能再浏览器中访问
                .select()
                //RequestHandlerSelectors , 配置要扫描接口的方式
                //basePackage: 指定要扫描的包
                //any(): 扫描全部
                //none(): 不扫描
                //withClassAnnotation: 扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation: 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.test.swagger.controller"))
                //paths() 过滤什么路径
                //.paths(PathSelectors.ant(/xxx))
                .build();
    }
    
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
    //额外信息
    Contact contact = new Contact("NAME","URL","EMAIL");
        return new ApiInfoBuilder(
                title:"SpringBoot中使用Swagger2构建RESTful APIs",
                description:"xxxxINFOxxxxxx",
                version:"1.0",
                termsOfServiceUrl:"xxxxURLxxxxxx",
                contact,
                license:"Apache 2.0",
                licenseUrl:"http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
      	);
    }
}

4：丰富文档内容

Swagger使用的注解及其说明：

@Api：用在类上来说明该类的作用

@ApiOperation：给方法添加说明

@ApiImplicitParams : 在方法上包含一组参数说明

@ApiImplicitParam：给方法入参增加说明

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

code：数字，例如400

message：信息，例如"请求参数没填好"

response：抛出异常的类   

@ApiModel：描述一个Model的信息

@ApiModelProperty：描述一个model的属性

5. 简单的UI

来自官网,与实际访问有差距

总结：

1. 以上Swagger注解给一些难理解的属性或者接口，添加注释信息

2. 接口文档实时更新

3.可以在线测试

[ 在正式发布时，要关闭Swagger ! 处于安全 也节省运行内存]