搭建-swagger2-swagger使用教程-实时生成接口文档-使用教程（springboot）

Swagger简介

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

现在开发的趋势都是分布式开发，所以对于生成接口文档也是一个十分重要的步骤，swagger刚好帮我们解决了这个问题，不仅可以生成文档，还可以在线进行接口的测试，十分之方便，现在我们来快速搭建

• 第一步引入Swagger2和swagger ui，可以在父工程引用，因为我们几乎每一个项目模块几乎都是要生成项目文档，在父工程引用我们继承父工程的模块都会依赖；

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>

• 第二部 编写配置类AppSwaggerConfig，同时在配置类加入==@EnableSwagger2的注解（开启swagger2自动生成api文档功能）；同时也不要忘记将配置类加入
  spring ioc容器中添加@Configuration==

@EnableSwagger2  //开启swagger2自动生成api文档的功能
@Configuration
public class AppSwaggerConfig {

}

• 现在就可以通过http://localhost:xxxx（项目端口）/swagger-ui.html来查看生成的文档，同时可以进行服务接口测试；
• 
• 如果搭建成功我们就会看到上面的页面
• 我们第一次使用模拟个接口HelloController

@RestController
public class HelloController {

	public String hello(String name,Integer age) {
		
		return "ok"+name+age;
		
	}
	
}

• 我们可以在页面中访问这个接口
• 
• 通过点击Try it out 我们就可以在线测试这个接口
• 
• 通过上图我的调用，我们可以看到整个传输数据的细节，这对于我们分布式的开发是十分不错的，不仅是远程调用别人的时候可以测试，自己的项目也可以十分方便的测试每个接口；

上面教大家如何搭建和调用接口

• 现在就是教大家如何生成详细文档 ------》使用swagger给我们提供的注解
• @Api(tags="")
  用在请求的类上，表示对类的说明
  tags"说明该类的作用，可以在UI界面上看到的注解"
• @ApiOperation(value="")
  用在请求的方法上，说明方法的用途、作用
  value=“说明方法的用途、作用”
• @ApiImplicitParams
  用在请求的方法上，表示一组参数说明
  – @ApiImplicitParam
  – @ApiImplicitParam:指定一个请求参数的各个方面
  – value：参数的汉字说明、解释
  – required：参数是否必须传
  – paramType：参数放在哪个地方
  – header –> 请求头的获取：@RequestHeader
  – query –> 请求参数的获取：@RequestParam
  – path（用于restful接口）–> 请求路径变量的获取：@PathVariable
  – body（不常用）
  – form（不常用）
  – dataType：参数类型，默认String，其它值dataType=“Integer”
  – defaultValue：参数的默认值
• @ApiResponses
  用在请求的方法上，表示一组响应
  – @ApiResponse
  – 用在@ApiResponses中，一般用于表达一个错误的响应信息
  – code：数字，例如400
  – message：信息，例如"请求参数没填好"
  – response：抛出异常的类
• @ApiModel
  – 主要有两种用途：
  – 用于响应类上，表示一个返回响应数据的信息
  – 入参实体：使用@RequestBody这样的场景， 请求参数无法使用@ApiImplicitParam注解进行描述的时候
  – @ApiModelProperty
  — 用在属性上，描述响应类的属性

比较常用的就是上面我标注的三个

• 我们需要标注这个类的作用，说明：@Api(tags="")
• 我们需要标注某个方法的说明： @ApiOperation(value="")
• 我们需要标注传入参数的说明：@ApiImplicitParams{@ApiImplicitParam}
• 看我下图对这三个注解的使用
• 
• 可以看到我对这个累的描述 和对hello方法描述 和对参数的描述
• 现在看到接口页面
• 

这样就结束了，如果没有用过的小伙伴肯定是会觉得很方便；