介绍
swagger是什么？
swagger-ui
使用swagger-ui
简单使用
swagger api注解
本文参考：
介绍
这里是一些介绍，如果想直接看如何使用，请直接跳过这部分。但如果有时间，就姑且看一下吧，这部分大概用时3分钟。
swagger是什么？
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。
目前的项目基本都是前后端分离，后端为前端提供接口的同时，还需同时提供接口的说明文档。但我们的代码总是会根据实际情况来实时更新，这个时候有可能会忘记更新接口的说明文档，造成一些不必要的问题。
用人话说，swagger就是帮你写接口说明文档的。更具体地，可以看下面的图片，swagger官方建议使用下面的红字部分，这篇博客主要是记录如何，使用swagger自动生成Api文档的，所以只介绍swagger-ui，其他的…以后我用到会再整理。
swagger-ui
用来显示API文档的，不可编辑，会根据我们在代码中的设置来自动生成Api说明文档。生成的api文档如下，不好意思，长得不太像文档…但比文档更清楚对不对！对！
本文中的举例全部基于spring boot，如果不太熟悉构建请移步：spring教程（一），既然写道这里，介绍一下项目需要的环境
编译器：IntelliJ IDEA .3.5 x64框架：spring-boot-cli-1.4.3.RELEASE-binswagger版本：springfox-swagger2，2.9.2
使用swagger-ui
通过第一部分“简单使用”能够让你快速地使用swagger-ui来生成api文档，之后会详细地解释swagger-ui一些注解及使用方法。如果想要看swagger-ui用到的一些注解的详细使用方法、说明、及示例请移步第二部分“swagger api注解”。
简单使用
以下操作基于spring教程（一）的项目内容，项目结构如下，比较简单。
简单地使用swagger-ui只需要三步。
第一步，配置pom文件。在pom文件中引入swagger的相关依赖，在“<dependencies></dependencies>”中间添加下面的依赖。
<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.8.0</version></dependency>
第二步，构建swagger配置类。我选择构建的位置是主目录下，目录并不会对运行结果产生影响，但整个项目只能有一个swagger配置类。配置类的代码如下，建议只粘贴类的代码部分，然后“alter+Enter”添加引入的包的部分。
import io.swagger.annotations.Api;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;/*** Swagger使用的配置文件*/@Configuration@EnableSwagger2public class Swagger2Configuration {@Beanpublic Docket createRestApi(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.withClassAnnotation(Api.class)).paths(PathSelectors.any()).build();}//基本信息的配置，信息会在api文档上显示private ApiInfo apiInfo(){return new ApiInfoBuilder().title("zg测试的接口文档").description("xx相关接口的文档").termsOfServiceUrl("http://localhost:8080/hello").version("1.0").build();}}
这里需要对第二步说明几点：
apiInfo：api基本信息的配置，信息会在api文档上显示，可有选择的填充，比如配置文档名称、项目版本号等apis：使用什么样的方式来扫描接口，RequestHandlerSelectors下共有五种方法可选。我们当前使用通过在类前添加@Api注解的方式，其他方法我们后续介绍。path：扫描接口的路径，PathSelectors下有四种方法，我们这里是全扫，其他方法我们后续介绍。
第三步，在接口文件中增加对应注解。代码如下，由于我们第二步选择扫描接口的方式是在类前添加@Api；@ApiOperation用于注明接口，value是接口的解释；@ApiParam注解函数里面的参数，name一般与参数名一致，value是解释，required是是否参数必须。
@Controller@Apipublic class HelloController {@ApiOperation(value = "你好")@ResponseBody@PostMapping("/hello")public String hello(@ApiParam(name="name",value="对话人",required=true)String name){return name+", hello";}}
上面操作都完成后，在浏览器中输入网址：http://localhost:8080/swagger-ui.html，我使用的接口是默认的8080，具体以自己项目的配置为准。
swagger api注解
这一部分除了，下面列出的注解外，还包括上面所介绍的RequestHandlerSelectors和PathSelectors的几种方法及含义。
@Api： 用于类，标识这个类是swagger的资源@ApiIgnore： 用于类，忽略该 Controller，指不对当前类做扫描@ApiOperation： 用于方法，描述 Controller类中的 method接口@ApiParam： 用于参数，单个参数描述，与 @ApiImplicitParam不同的是，他是写在参数左侧的。如（ @ApiParam(name="username",value="用户名")Stringusername）@ApiModel： 用于类，表示对类进行说明，用于参数用实体类接收@ApiProperty：用于方法，字段，表示对model属性的说明或者数据操作更改@ApiImplicitParam： 用于方法，表示单独的请求参数@ApiImplicitParams： 用于方法，包含多个 @ApiImplicitParam@ApiResponse： 用于方法，描述单个出参信息@ApiResponses： 用于方法，包含多个@ApiResponse@ApiError： 用于方法，接口错误所返回的信息
本文参考：
超详细 swagger api注解spring boot项目中使用swagger25分钟了解swagger官方Class RequestHandlerSelectors文档如果觉得《超详细！使用swagger自动生成Api文档（swagger-ui）》对你有帮助，请点赞、收藏，并留下你的观点哦！
