Swagger接口管理工具

1、概念

Swagger就是一个用来定义接口标准，接口规范，同时能根据你的代码自动生成接口说明文档的一个工具。
官方网址：https://swagger.io/

2、官方工具介绍

Swagger Codegen：通过Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多种语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

Swagger UI：提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

Swagger Editor：类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

Swagger Inspector：和postman类似，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

Springfox Swagger：Spring基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的。

3、SpringBoot整合Swagger

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、编写Swagger配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
   @Bean
   public Docket createRestApi(){
       return new Docket(DocumentationType.SWAGGER_2)
         .pathMapping("/")
         .select()  
         .apis(RequestHandlerSelectors.basePackage("com.example.springbootjpa.controller"))
         .paths(PathSelectors.any())
         .build().apiInfo(new ApiInfoBuilder()
             .title("利用swagger2构建的API文档")
             .description("用restful风格写接口")
             .version("1.0")
             .contact(new Contact("xiaoming","www.baidu.com","xiaoming@163.com"))
             .license("The Baidu License")
             .licenseUrl("http://www.baidu.com")
             .build();
   }
}

3、访问Swagger的UI界面
路径：http://localhost:8080/swagger-ui.html

4、注解使用说明

@Api

作用：用来指定接口的描述文字
修饰范围：用在类上

@RequestMapping( "user" )
@Api(tags ="用户模块接口规范说明")
public class UserController {
   .......
}

@ApiOperation

作用：用来对接口中具体方法做描述
修饰范围：用在方法上

GetMapping( "findAll")
@ApiOperation(value = "查询所有用户接口”,
                         notes = "espan style='color:red;'>描述：</span>&nbsp；用来查询所有用户信息的接口")
public Map<String,object> findAll(){
  Map<String,Object> map = new HashMap<String,0bject>();
  map.put( "success","查询所有成功!");
  map.put( "state" ,true);
  return map;
 }
 
value:用来对接口的说明
notes:用来对接口的详细描述

@ApilmplicitParams

作用：用来接口的中参数进行说明
修饰范围：用在方法上

@ApiImplicitParams({
  @ApiImplicitParam(name="id" ,value = "用户id" ,dataType = "string" ,defaultValue = "21")，
  @ApiImplicitParam(name="name" , value =“用户姓名" , dataType ="String" ,defaultValue =“张三")
})
public Map<String，Object> save(String id，String name) {
  ......
}

@ApiResponses

作用：用于请求的方法上，表示一组响应
修饰范围：用在方法上

@ApiResponses( {
	@ApiResponse(code = 400，message ="请求参数没填好")，
	@ApiResponse(code = 404，message ="请求路径没有或页面跳转路径不对")
 })
public Map<String，Object> save(String id，String name) {
  ......
}