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();                                           
    }
}

③集成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
本文只简单介绍常用的部分注解及其属性