Swagger2的第一个HelloWorld程序

一、Swagger2是什么

官方：Swagger是一个规范的、完整的的框架 这个框架主要的功能是生成、描述、调用和可视化的RESFful风格的服务

Swagger是一个生成接口文档、以及接口描述、以及测试的这样一个框架

1、前后分离以及给穿戴设备提供接口的分析

2、存在的一些问题

3、Swagger2到底是什么?

这个东西简单的说 就是可以将我们写的这个接口自动生成文档 以及测试环境

二、Swagger2中的一些组件

Swagger是一个开源的项目

Swagger-tools:主要存放的是和Swagger集成和整合的工具

Swagger-core：主要就是整个Swagger的核心

Swagger-js：主要是用在JavaScript上的Swagger实现

Swagger-ui：Swagger自动生成文档的这一部分API

三、Swagger的第一个HelloWorld程序

1、导包

 <!--导包-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>

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

2、编写配置文件

@SpringBootConfiguration       //表明是一个配置文件
@EnableSwagger2                //使能Swagger
public class SwaggerConfig {
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())        //这个方法的作用（生成接口的时候页面显示的信息）
                .select()         //表示的是选择那些路径和API生成文档
                .apis(RequestHandlerSelectors.basePackage("com.qf.springboot.controller"))           //告诉他要扫描的接口存在的这个包
                .paths(PathSelectors.any())          //对所有的API进行监控
                .build();         //构建
    }

    /**
     * 这个方法主要的作用是显示页面上的信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("这里是测试Swagger2的功能文档")    //文档的标题
                .description("这里是NZ1904测试用的")      //文档的描述
                .contact("小波波")                        //作者
                .version("v1.0")                          //版本
                .build();
    }
}

3、测试

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

如果出现Swagger描述的这个页面说明是正确的

4、传单无参的写法

 /**
     * 没有参数的玩法
     * @return
     */
    @RequestMapping(value = "test",method = RequestMethod.GET)
    @ApiOperation(value = "测试接口1")
    public RespResult<String> test(){

        RespResult<String> result = new RespResult<>();
        result.setCode(1);
        result.setMsg("请求成功");
        result.setData("xxxxxxxxxxxxxxxxx");

        return  result;
    }

5、传递有参数的时候的写法

 /**
     * 有简单参数的玩法
     *    @ApiImplicitParam注解中参数的说明
     *    header：请求的数据放在请求头里面的 就用这个类型
     *    query：请求的参数 放到了请求地址上、配套的（@requestParam）
     *    path：（RestFul中用于面向资源编程的获取数据的方式），配套的获取数据的注解 @PathVarible
     *    body(不会用)
     *    form(基本不用)
     * @return
     */
    @RequestMapping(value = "test1",method = RequestMethod.GET)
    @ApiOperation(value = "测试接口1")
    /**
     * paramType：类型(数据放在那里的问题)
     * name：说明的是参数的名字叫什么
     * value：当前参数的含义
     * required：当前使用这个接口对哦时候 这个参数是不是一定要传
     * dataType：参数的类型
     *
     */
    @ApiImplicitParam(paramType = "query",name = "userName",value = "用户名",required =true,dataType = "String")
    public RespResult<String> test(@RequestParam("userName") String userName){
        RespResult<String> result = new RespResult<>();
        result.setCode(1);
        result.setMsg("请求成功");
        result.setData("xxxxxxxxxxxxxxxxx:"+userName);
        return  result;
    }

6、传递多参数的写法

 /**
     * 有多个参数的玩法
     * @return
     */
    @RequestMapping(value = "test4",method = RequestMethod.GET)
    @ApiOperation(value = "测试接口4",notes = "调用当前方法的注意事项")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query",name = "userName",value = "用户名",required =true,dataType = "String"),
            @ApiImplicitParam(paramType = "query",name = "password",value = "密码",required =true,dataType = "String")

    })
    public RespResult<String> test3(@RequestParam("userName") String userName,@RequestParam("password") String password){
        RespResult<String> result = new RespResult<>();
        result.setCode(1);
        result.setMsg("请求成功");
        result.setData("xxxxxxxxxxxxxxxxx:"+userName+"----:"+password);
        return  result;
   }

7、传递对象

7.1、对象的写法

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "用户对象")
public class User {
    @ApiModelProperty(value = "用户id")
    private int id;
    @ApiModelProperty(value = "用户名")
    private String userName;
    @ApiModelProperty(value = "密码")
    private String password;
}

7.2、方法的写法

    /**
     * 有多个参数的玩法
     * @return
     */
    @RequestMapping(value = "test5",method = RequestMethod.POST)
    @ApiOperation(value = "测试传递对象过来",notes = "调用当前方法的注意事项")
    public RespResult<User> test5(@RequestBody User user){
        RespResult<User> result = new RespResult<>();
        result.setCode(0);
        result.setMsg("请求成功--------");
        result.setData(user);
        return  result;
    }

7.3、前后分离请求资源的流程

7.4、Swagger支持token的传输

  @RequestMapping(value = "test6",method = RequestMethod.POST)
    @ApiOperation(value = "测试传递对象过来",notes = "调用当前方法的注意事项")
    @ApiImplicitParam(paramType = "header",name = "token",value = "用户token",required = true,dataType = "String")
    public RespResult<User> test6(@RequestBody User user, HttpServletRequest request){
        String token=request.getHeader("token");
        RespResult<User> result = new RespResult<>();
        result.setCode(0);
        result.setMsg("请求成功--------:"+token);
        result.setData(user);
        return  result;
    }

7.5、Swagger如何测试文件的上传

 /**
     * Swagger测试文件上传的方法
     * @param request
     * @param uId
     * @param file
     * @return
     */
    @RequestMapping(value = "fileupload",method = RequestMethod.POST)
    @ApiOperation(value = "测试文件上传",notes = "调用当前方法的注意事项")
    @ApiImplicitParams(
            {
                    @ApiImplicitParam(paramType = "header",name = "token",value = "用户token",required = true,dataType = "String"),
                    @ApiImplicitParam(paramType = "query",name = "uId",value = "用户的id",required = true,dataType = "Integer")
            }
    )
    public RespResult<String> fileupload(HttpServletRequest request,@RequestParam("uId")int uId,@RequestParam("file") MultipartFile file){
        String token=request.getHeader("token");
        RespResult<String> result = new RespResult<>();
        //接下来就可以将文件另存了
        try {
            file.transferTo(new File("G:/bobo.jpg"));
            result.setCode(0);
            result.setMsg("请求成功--------:"+file.getOriginalFilename());
            result.setData("上传是成功的");
        } catch (IOException e) {
            result.setCode(1);
            result.setMsg("上传是失败的:"+e.getMessage());
            result.setData("");
        }
        return  result;
    }

希望大家关注我一波,防止以后迷路,有需要的可以加我Q讨论互相学习java ,学习路线探讨,经验分享与java Q:2415773436