Swagger的简介与使用方法
一：Swagger is what？
1、是一款让你更好的书写API文档的规范且完整框架。
2、提供描述、生产、消费和可视化RESTful Web Service。
3、是由庞大工具集ruhe合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。
二：如何使用Swagger？
1.与SpringBoot项目集成 =====>
在pom.xml文件中添加swagger相关依赖
io.springfox
springfox-swagger2
2.8.0
io.springfox
springfox-swagger-ui
2.8.0
尽量下载高的版本号，不然会出现下面类类似情况：
***************************
APPLICATION FAILED TO START
***************************
Description:
Parameter 0 of method linkDiscoverers in org.springframework.hateoas.config.HateoasConfiguration required a single bean, but 15 were found:
- modelBuilderPluginRegistry: defined in null
- modelPropertyBuilderPluginRegistry: defined in null
- typeNameProviderPluginRegistry: defined in null
- documentationPluginRegistry: defined in null
- apiListingBuilderPluginRegistry: defined in null
- operationBuilderPluginRegistry: defined in null
- parameterBuilderPluginRegistry: defined in null
- expandedParameterBuilderPluginRegistry: defined in null
- resourceGroupingStrategyRegistry: defined in null
- operationModelsProviderPluginRegistry: defined in null
- defaultsProviderPluginRegistry: defined in null
- pathDecoratorRegistry: defined in null
- relProviderPluginRegistry: defined by method 'relProviderPluginRegistry' in class path resource [org/springframework/hateoas/config/HateoasConfiguration.class]
- linkDiscovererRegistry: defined in null
- entityLinksPluginRegistry: defined by method 'entityLinksPluginRegistry' in class path resource [org/springframework/hateoas/config/WebMvcEntityLinksConfiguration.class]2.配置Swagger （也就是创建个类Swagger2 + 注解 就完事了）
@Configuration //等价于 @Component
@EnableSwagger2 //开启swagger2
public class Swagger2 {
}
3.启动项目 测试 ：（访问ui页面路径：localhost：8080/swagger-ui.html ）
完事了！！！ 这就成功了 。
真正开发情况下，swagger配置得配全面。继续往下看把。
@Configuration //等价于 @Component
@EnableSwagger2 //开启swagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.yuqi.demo.controller")) //扫描指定接口所在得路径
.paths(PathSelectors.any())
.build();
}
//编写swagger 信息，可在ui页面显示
private ApiInfo apiInfo() {
Contact contact = new Contact("小健","https://blog.csdn.net/qq_35370485","[email protected]");
return new ApiInfoBuilder()
.title("服务APIs") //
.description("只有登上山峰，山才会支撑你")
.termsOfServiceUrl("https://blog.csdn.net/qq_35370485")
.contact(contact) //作者信息
.version("1.0")
.build();
}
}Controller层：
@RestController
@Component
@Api(value = "测试接口",tags = "测试") //
public class HelloController {
@RequestMapping("/hello")
public String testHello(){
return "hello";
}
}
swagger注解：
1、@Api()：用在请求的类上，表示对类的说明，也代表了这个类是swagger2的资源
参数：
tags：说明该类的作用，参数是个数组，可以填多个。
value="该参数没什么意义，在UI界面上不显示，所以不用配置"
description = "用户基本信息操作"2、@ApiOperation()：用于方法，表示一个http请求访问该方法的操作
参数：
value="方法的用途和作用"
notes="方法的注意事项和备注"
tags：说明该方法的作用，参数是个数组，可以填多个。
格式：tags={"作用1","作用2"}
（在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）3、@ApiModel()：用于响应实体类上，用于说明实体作用
参数：
description="描述实体的作用" 4、@ApiModelProperty：用在属性上，描述实体类的属性
参数：
value="用户名" 描述参数的意义
name="name" 参数的变量名
required=true 参数是否必选5、@ApiImplicitParams：用在请求的方法上，包含多@ApiImplicitParam
6、@ApiImplicitParam：用于方法，表示单独的请求参数
参数：
name="参数ming"
value="参数说明"
dataType="数据类型"
paramType="query" 表示参数放在哪里
· header 请求参数的获取：@RequestHeader
· query 请求参数的获取：@RequestParam
· path（用于restful接口） 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
defaultValue="参数的默认值"
required="true" 表示参数是否必须传7、@ApiParam()：用于方法，参数，字段说明 表示对参数的要求和说明
参数：
name="参数名称"
value="参数的简要说明"
defaultValue="参数默认值"
required="true" 表示属性是否必填，默认为false8、@ApiResponses：用于请求的方法上，根据响应码表示不同响应
一个@ApiResponses包含多个@ApiResponse
9、@ApiResponse：用在请求的方法上，表示不同的响应
参数：
code="404" 表示响应码(int型)，可自定义
message="状态码对应的响应信息" 10、@ApiIgnore()：用于类或者方法上，不被显示在页面上
11、@Profile({"dev", "test"})：用于配置类上，表示只对开发和测试环境有用