Swagger

简介

Swagger的描述就不多说了，用简单一句话概括：Swagger是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的优势

支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对我们来说非常方便，可以节约写文档的时间。
提供 Web 页面在线测试 API：除了生成相关接口文档外，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

使用场景

使用背景是一个旧项目，这个项目缺少接口文档，BS端尚可使用浏览器获取请求接口，如果CS端需要接口文档时还得手动去抓包，这时就体现出项目文档的重要性。Swagger就是一个很好的选择，给定一个统一管理平台去管理整个项目的接口文档，规范之后，方便整个项目组使用。
框架为SSM，所以下面样例为springMvc集成Swagger

使用步骤

导入maven依赖

<!-- swagger -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.6.1</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.6.1</version>
</dependency>

---

配置spring-mvc.xml

在配置文件当中添加

<!--配置swagger-->
<bean class="com.tf.SwaggerConfig" id="swaggerConfig"></bean>

SwaggerConfig配置类

@EnableWebMvc
@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.tf"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("接口列表 v1.0.0")
                .description("swagger接口列表")
                .termsOfServiceUrl("http://loacalhost:8080/")
                .version("1.0.0")
                .build();
    }

}

配置类和springboot大致一样，只是需要多一个@EnableWebMvc注解。
配置内容包括ui界面的信息、包扫描路径的信息。

---

编写controller类

@Api(value = "设备管理")
@RestController
@RequestMapping("/testApi")
public class TestSwaggerController {

    @ApiOperation(value = "查询设备", notes = "查询设备列表")
    @GetMapping("/getList")
    public Object getList(@ApiParam(value = "设备id 这个是参数描述", required = false) Integer objId) {
        List<?> all = CommonDBInstance.getInstance().getAll(ObjMonitored.class);
        return CtrlBase.responseObject(all,"");
    }

    @ApiOperation("保存设备")
    @ApiImplicitParam(name = "obj", value = "单个设备信息", dataType = "User")
    @PostMapping("/save")
    public Object save(ObjMonitored obj) {
        return CtrlBase.responseSucc("");
    }

    @ApiOperation("更新设备")
    @ApiImplicitParam(name = "obj", value = "单个设备信息", dataType = "User")
    @PutMapping("/update")
    public Object update(ObjMonitored obj) {
        return CtrlBase.responseSucc("");
    }

    @ApiOperation("删除设备")
    @DeleteMapping("/delete")
    public Object delete(@ApiParam(value = "设备id 这个是参数描述", required = false) Integer objId) {
        return CtrlBase.responseSucc("");
    }
}

启动服务

访问：http://localhost:8080/swagger-ui.html

UI主页面

接口详情

---

注解说明

@Api：用在请求的controller类上，表示对类的说明，也代表了这个类是swagger2的资源
参数：
        tags：说明该类的作用，参数是个数组，可以填多个
        value：忽略
        description ：请求类的描述

@ApiOperation：用于方法，表示访问该方法的操作
参数：
        value：方法的用途和作用
        notes：方法的备注
        tags：说明该方法的作用，参数是个数组，可以填多个

@ApiModel：用于实体bean上，用于说明实体作用
参数：
        description：实体bean的描述

@ApiModelProperty：用在实体bean的字段，描述实体类字段的属性
参数：
        value：参数描述
        name：参数的变量名
        required：参数是否必填

@ApiImplicitParam：用于方法，表示单独的请求参数
参数：
        value：参数描述
        name：参数的变量名
        dataType：数据类型
        defaultValue：参数的默认值
        required：参数是否必填
        paramType：表示参数放在哪里，可选值有：header，query，path 还有 body 和 form
还有一个@ApiImplicitParams，见名知意，@ApiImplicitParam的复数形式

@ApiParam()：用于方法，参数，字段说明 表示对参数的要求和说明
参数：
        value：参数描述
        name：参数的变量名
        required：参数是否必填
        defaultValue：参数的默认值

@ApiIgnore()：用于类或者方法上，表示不被显示在页面上

上面就是swagger的用法了，demo中只使用了部分注解，可自行根据业务选择对应的注解使用。

swagger也有缺点
        其一就是代码侵入性太强，但是为了满足我们的需求，一些缺点也可以接受。
        其二就是swagger属于裸奔型文档，开发环境还好，如果是生产环境呢？

解决方案
        推荐一个插件，knife4j 官方网址 ，主要功能对swagger进行了封装增强，美化了UI界面、优化了swagger测试流程等优点，最主要的是增加了权限控制，在生产环境下屏蔽所有文档接口，测试环境下也可以增加登录校验和分组权限管理，完全可以满足我们的需求。

使用步骤

添加maven依赖

<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>swagger-bootstrap-ui</artifactId>
	<version>1.9.6</version>
</dependency>

springboot直接在yml里面配置即可。
因为这里是springMVC集成swagger，springMvc需要配置在web.xml页面

<!--生产环境Filter-->
<filter>
	<filter-name>swaggerProductionFilter</filter-name>
	<filter-class>com.github.xiaoymin.swaggerbootstrapui.filter.ProductionSecurityFilter</filter-class>
	<init-param>
		<param-name>production</param-name>
		<!--生产环境时开启，屏蔽所有接口文档-->
		<param-value>false</param-value>
	</init-param>
</filter>
<filter-mapping>
	<filter-name>swaggerProductionFilter</filter-name>
	<url-pattern>/*</url-pattern>
</filter-mapping>
<!--测试环境Filter-->
<filter>
	<filter-name>swaggerSecurityBasic</filter-name>
	<filter-class>com.github.xiaoymin.swaggerbootstrapui.filter.SecurityBasicAuthFilter</filter-class>
	<init-param>
		<param-name>enableBasicAuth</param-name>
		<param-value>true</param-value>
	</init-param>
	<!--用户名和密码配置-->
	<init-param>
		<param-name>userName</param-name>
		<param-value>admin</param-value>
	</init-param>
	<init-param>
		<param-name>password</param-name>
		<param-value>123456</param-value>
	</init-param>
</filter>
<filter-mapping>
	<filter-name>swaggerSecurityBasic</filter-name>
	<url-pattern>/*</url-pattern>
</filter-mapping>

配置web.xml即可完成knife4j的配置。如果是springboot，将上面的配置在yml里面即可

启动之后访问knife4j提供的：http://localhost:8080/doc.html，此时无需再访问/swagger-ui.html页面了

但是生产环境时需要将enableBasicAuth设置为true，即屏蔽所有文档接口

输入网址后，即可看到久违的登录页面

登录之后的界面

接口详情页面

接口里面优化了在线调试

---

上面就是swagger的基本用法了，总体来说对于中小型项目来讲，swagger还是一个不错的工具，最起码能保证基本的文档，至于代码侵入性和使用灵活性等缺点，可衡权利弊自行选择使用