Swagger

1 swagger运行

引用至： https://blog.csdn.net/sanyaoxu_2/article/details/80555328

导入相应的依赖

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>

在Config包底下创建Swagger2

@Configuration
@EnableSwagger2
public class Swagger2 {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多请关注http://www.baidu.com")
                .termsOfServiceUrl("http://www.baidu.com")
                .contact("sunf")
                .version("1.0")
                .build();
    }

}

.apis(RequestHandlerSelectors.basePackage(“com.controller.HelloController”)): 注意 这里说明的是Controller包的位置， 不是Controller类的全类名

相应的Controller

@Controller
@RequestMapping("/say")
@Api(value = "SayController | 一个用来测试swagger注解的控制器")
public class HelloController {

    @ResponseBody
    @RequestMapping(value ="/getUserName", method= RequestMethod.GET)
    @ApiOperation(value="根据用户编号获取用户姓名", notes="test: 仅1和2有正确返回")
    @ApiImplicitParam(paramType="query", name = "userNumber", value = "用户编号", required = true, dataType = "Integer")
    public String getUserName(@RequestParam Integer userNumber){
        if(userNumber == 1){
            return "张三丰";
        }
        else if(userNumber == 2){
            return "慕容复";
        }
        else{
            return "未知";
        }
    }

    @ResponseBody
    @RequestMapping("/updatePassword")
    @ApiOperation(value="修改用户密码", notes="根据用户id修改密码")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query", name = "userId", value = "用户ID", required = true, dataType = "Integer"),
            @ApiImplicitParam(paramType="query", name = "password", value = "旧密码", required = true, dataType = "String"),
            @ApiImplicitParam(paramType="query", name = "newPassword", value = "新密码", required = true, dataType = "String")
    })
    public String updatePassword(@RequestParam(value="userId") Integer userId, @RequestParam(value="password") String password,
                                 @RequestParam(value="newPassword") String newPassword){
        if(userId <= 0 || userId > 2){
            return "未知的用户";
        }
        if(StringUtils.isEmpty(password) || StringUtils.isEmpty(newPassword)){
            return "密码不能为空";
        }
        if(password.equals(newPassword)){
            return "新旧密码不能相同";
        }
        return "密码修改成功!";
    }

}

完成上述代码添加上，启动Spring Boot程序，访问：

http://localhost:8080/swagger-ui.html

@Api：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。
参数：
   ·paramType：指定参数放在哪个地方
      ··header：请求参数放置于Request Header，使用@RequestHeader获取
      ··query：请求参数放置于请求地址，使用@RequestParam获取
      ··path：（用于restful接口）-->请求参数的获取：@PathVariable
      ··body：（不常用）
      ··form（不常用）
   ·name：参数名
   ·dataType：参数类型
   ·required：参数是否必须传(true | false)
   ·value：说明参数的意思
   ·defaultValue：参数的默认值

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
      ——code：数字，例如400
      ——message：信息，例如"请求参数异常!"
      ——response：抛出异常的类   

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiModelProperty：描述一个model的属性

2 每一步分析

首先在config类上标注@Configuration
然后加上@EnableSwagger2
#

1.1 @Configuration的作用

是一个接口

指示一个类声明一个或者多个@Bean 声明的方法并且由Spring容器统一管理
一看到这个注解，我们最浅显的理解就是 这个是取代Spring中的xml配置的。
在类上面标注了@Configuration 指明这是一个Spring的配置文件。
在Spring中我们通过添加@Bean到方法体上。
把它注入到Spring容器中。

1.2 @EnableSwagger2的作用

通过Bean把Docket注入到Spring的容器中。

1.3 比较好奇Docket是干嘛的？ 为什么要用它？

Docket ： 摘要，记事表
进入Docket类中查看源码

有一个有参构造器，形参是文件类型DocumentationType
打开DocumentationType类，继承SimplePluginMatadata（简易插件数据）

在这个类中，有有参构造器，其中是插件的名字和版本。

1.3.1 API指的是什么？

api 根据英文解释就是 java application interface 应用程序接口
其后有.apiInfo() 调用方法apiInfo 接口信息输入

查看一下

在当前类的方法下面我们自己写上apiInfo 信息录入。

添加标题，描述，版本等等，最后在建立。

.select() 选择 程序接口建立（当前Docket）

.apis(RequestHandlerSelectors.basePackage(“com.controller.HelloController”))
.apis() : 指定所有的接口，告诉明确的路径 请求处理器选择.包名为 “XXX”
.paths(PathSelectors.any())
.paths(): 指定路径
.build(); 然后建立。

1.4 为什么每次在@Configuration中写入Bean都是放回一个实例对象？