一文教你使用Swagger---适合新手小白（结合实战）

1.什么是Swagger 

   Swagger----在线自动生成接口文档，是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，可用于接口的文档在线自动生成以及功能测试。

2.Swagger与OpenAPI  

   OpenAPI规范OpenAPI Specification以前叫做Swagger规范，是REST API的API描述格式。Open API 文件允许描述整个API,包括：

• 每个访问地址的类型，POST或GET
• 每个操作的参数，包括输入输出参数
• 认证方法
• 连接信息、声明，使用团队和其他信息

   OpenAPI规范可以使用YAML或jSON格式进行编写，这样更利于阅读。Swagger是一套围绕Open API规范构建的开源工具，可以帮助设计、构建，记录和使用REST API。

3.Swagger工具包括的组件

Swagger Editor：基于浏览器编辑器，可以在里面编写Open API规范。类似Markdown具有实时预览描述文件的功能。

Swagger UI：将Open API规范呈现为交互式API文档。用可视化UI展示描述文件。

Swagger Codegen：将OpenAPI规范生成为服务器存根和客户端库，通过Swagger Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也可以生成多种语言的客户端和服务端代码。

Swagger Inspector：和Swagger UI欧典类似，但是可以返回更多信息，也会保存请求的实际参数数据。

Swagger Hub 继承了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作。需要注册帐号，分免费版和收费版。使用Swagger，就是把相关的信息存储在他定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

4.Springfox的使用

1.引入依赖

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

2.启动类上加注解

3.启动后浏览器输入对应端口号+/swagger-ui.html.

我的是 http://localhost:8080/swagger-ui.html#

4.效果如下

5.SwaggerUI的使用和配置

    访问swagger-ui.html可以在页面中看到所有需要生成接口文档的控制器名称。

    每个控制包含该控制器下所有的方法及访问方式。如果使用的是@RequestMapping进行映射，将在显示所有的请求方式，如上图所示。假设使用@PostMapping，那么就只会显示Post的那个。

点击某个请求方法中的try it out

 输入对应的参数，然后点击execute执行，将会出现Request URL以及相应结果。

5.Swagger配置类的实现

效果：

6.自定义注解排除扫描

1.创建NoIncludeSwagger接口

package cn.itcast;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface NoIncludeSwagger {
}

2.配置到Swagger配置类中

3.在需要排除了类上加上注解即可

效果如下：

7.设置范围

所谓设置范围实际就是可以设置满足什么样规则的url能被生成在接口文档中，可以使用正则表达式进行匹配。

下面例子中表示只有以/demo/开头的url才能被swagger生成接口文档。

如果希望所有接口都使用Swagger：

paths(PathSelectors.any())

8.常用注解

  1. Api

注解名称	参数	含义
@Api		类上注解，控制整个类生成接口信息的内容
	tags	类的名称，可以有多个值，多个值表示多个副本
	description	概述

类上注解 控制整个类生成接口信息的内容

package cn.itcast.controller;

import cn.itcast.NoIncludeSwagger;
import cn.itcast.domain.People;
import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/people")
@Api(tags = {"myDemo"},description = "描述")
public class DemoController {
//    @NoIncludeSwagger
    @PostMapping("/getPeople")
    public People getPeople(Long id, String name){
        People peo = new People();
        peo.setId(id);
        peo.setName(name);
        peo.setAddress("北京");
        return peo;
    }
}

2. ApiOperation

注解名称	参数	含义
@ApiOperation		写在方法上，对方法进行总体描述
	value	接口描述
	notes	提示信息

@RestController
@RequestMapping("/people")
@Api(tags = {"myDemo"},description = "描述")
public class DemoController {
//    @NoIncludeSwagger
    @ApiOperation(value = "获取人员信息",notes = "通过人员编号和名称获取人员信息")
    @PostMapping("/getPeople")
    public People getPeople(Long id, String name){
        People peo = new People();
        peo.setId(id);
        peo.setName(name);
        peo.setAddress("北京");
        return peo;
    }
}

3. ApiParam

注解名称	参数	含义
@ApiParam		写在方法参数前面。用于对参数进行描述或说明是否为必填项等
	name	参数名称
	value	参数描述
	required	是否是必须

4. ApiModel

注解名称	参数	含义
@ApiParam		是类上注解，主要应用Model，也就是说这个注解一般都是写在实体类上
	value	名称
	description	描述

5. ApiModelProperty

注解名称	参数	含义
@ApiModelProperty		一般用于方法，属性的说明
	value	字段说明
	name	重写属性名
	required	是否必须
	example	示例内容
	hiden	是否隐藏

6. ApiIgnore

注解名称	含义
@ApiIgnore	用于方法或类或参数上，表示这个方法或类被忽略，和之前讲解的自定义注解@NotIncludeSwagger效果类似。只是这个注解是Swagger内置的注解，而@NotIncludeSwagger是我们自定义的注解

7. ApiImplicitParam

注解名称	参数	含义
@ApiImpliciParam		用在方法上，表示单独的请求参数，总体功能和@ApiParam类似。
	value	对接口中的参数进行简单必要的描述
	name	描述接口中参数的名称
	required	是否必须
	paramType	接口中的参数应该用在那个地方，常用的位置有：header,query,path
	dataType	接口中参数的类型

由于后两个效果类似与前面就不再做演示