swagger

了解更多

一、简介

Swagger是一种REST APIs的简单但强大的表示方式，标准的，语言无关，这种表示方式不但人可读，而且机器可读。可以作为REST APIs的交互式文档，也可以作为REST APIs的形式化的接口描述，生成客户端和服务端的代码。
docs ： swagger docs

---

二、为什么选择Swagger

1. 使用Swagger UI生成的界面比Javadoc生成的界面美观
2. swagger可以实时同步API文档(代码修改后，文档同步修改)
3. swagger解析速度快，效率高(使用轻量级数据交换格式JSON)
4. 对现有SpringMVC工程支持友好
5. Swagger可以充当前后端交流的重要桥梁，方便快捷。很实用。
6. Swagger项目允许你生产，显示和消费你自己的RESTful服务。不需要代理和第三方服务。是一个依赖自由的资源集合，它能通过Swagger API动态的生成漂亮的文档和沙盒,因为Swagger UI没有依赖，你可以把他部署到任何服务器环境或者是你自己的机器。

---

三、如何使用Swagger

3.1Swagger UI简介

Swagger UI是Swagger中用于显示Rest接口文档的项目，项目由一组HTML，JavaScript和CSS组成，没有外部依赖。Swagger UI可以根据Swagger Spec的json动态生成漂亮的帮助文档。支持常见浏览器。
(Swagger Spec是Swagger用于描述REST APIs的语言，可用json/yaml表示)
了解更多

1、支持API自动生成同步的在线文档，这些文档可用于项目内部API审核方便测试人员了解API
2、这些文档可作为客户产品文档的一部分进行发布
3、支持API规范生成代码，生成的客户端和服务器端骨架代码可以加速开发和测试速度

3.2开发步骤

参考

①添加依赖

      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger.version}</version>
      </dependency>
      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${swagger.version}</version>
      </dependency>

其中swagger.version自由控制

②写Java配置类

@PropertySource("classpath:swagger.properties")
@Configuration
@EnableSwagger2
public class SwaggerConfig {                                    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                           
    }
}

注解/方法	说明
@PropertySource	重写Swagger访问路径，默认的是/v2/api-docs
@Configuration	将这个类注入到Spring中并视作配置类
@EnableSwagger2	使Swagger2在工程中可用
swagger.preoperties	springfox.documentation.swagger.v2.path=/my/api-docs
DocumentationType.SWAGGER_2	默认final类型，自带属性name=swagger version=2.0
select()	返回一个ApiSelectorBuilder的实例，提供一种控制Swagger发布的方式
apis()	解析范围控制，例如.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
paths()	解析路径控制，通过any(),none(),regex(),或者ant()来控制，例如path(PathSelectors.ant("/foos/*"))
build()	生成Docket对象

③集成Swagger UI到工程中

1.从github上下载swagger-ui的zip包
2.复制dist文件夹下的内容到webapp目录下
3.修改index.xml的预访问地址为自定义的

4.修改web.xml文件中过滤器的匹配路径为/
5.因为swagger-ui项目都是静态资源，restful形式的拦截方法会将静态资源进行拦截处理，所以在springmvc配置文件中需要配置对静态文件的处理方式。
<mvc:default-servlet-handler/>

此举是为了体验最新版的swagger-ui，并且可以高度自定义内容，其实在springfox-swagger-ui中已经集成了大多数资源，如html页面和js文件等，当存在注解@EnableSwagger2时，就可以使用http://ip:host/swagger-ui.html查看接口文档

3.3注解说明

Javadocs for annotations with the current release are here
本文只简单介绍常用的部分注解及其属性

注解名	常用属性	使用描述
@Api	description、basepath、position已过时(deprecated) String[] tags 描述类,可以对该资源(控制器类)下的操作(函数)进行分类，列表中每个tag为一类 String value 描述类，会被tags覆盖，1.5版本后推荐使用tags String produces 描述内容类型，如application/json, application/xml boolean hidden 是否隐藏资源下的操作	使一个类成为Swagger资源，一般标在控制器上，与@Controller同级
@ApiOperation	String value required 简单描述此操作 boolean hidden 是否隐藏此操作 String nickName 相当于 operationId Class<?> response 返回类型 String notes 描述信息	标在操作上
@ApiParam	String name 参数名，如果不写会从地址中找/field/method/parameter name String value 简明描述 String required 是否必须	标在操作中的参数上
@ApiModel	String value 实体类名字描述，默认为类名 String description 简单描述实体类 Class<?> parent 提供一个父类，以便于描述继承	标在实体类上，描述实体类的信息，如果不标，但是在操作中用到了相关实体类，该实体类会被自动标注，属性信息为默认描述
@ApiModelProperty	String value 简明描述 String name 名字 String allowableValues 允许的值，两种写法，枚举式： {first,second,third} ，区间式：range[1,5],可开可闭，无穷用infinity表示 String dataType 数据类型，可以是类名或者简单类型，会覆盖掉读取到的类型 boolean required 参数是否必须 boolean readOnly 是否只读 String example 举例子 boolean allowEmptyValue 允许空值	标在实体类的属性上
@ApiImplicitParam	类似ApiParam	用于使用Servlet或者无JAX-RS环境时，或者@ApiParam被占用，可以手动声明单个参数
@ApiResponse	int code HTTP状态码，required String message 关于此状态码的相关描述，required	标在操作上，但是推荐用@ApiOperation来描述返回信息

---