Swagger2

Swagger2

介绍

Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。

可以帮助我们生成接口文档，并且可以在文档上直接进行接口测试

集成

依赖

<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>

启动类上加入

@EnableSwagger2

访问测试

http://localhost:8080/swagger-ui.html 注意使用自己的ip地址和端口号

应用

Controller

类上

@Api 注解 可设置对控制器的描述
tags 控制器标签。
description 描述

@RestController
@CrossOrigin
@RequestMapping("/brand")
@Api(tags = "品牌相关接口",description = "提供品牌相关的增删改查")
public class BrandController {

方法上

@ApiOperation
value 接口名
notes 接口说明

    @GetMapping("/{id}")
    @ApiOperation(value = "根据id查询",notes = "我是标题")
    public Result findById(@PathVariable Integer id){
        Brand brand = brandService.findById(id);
        return new Result(true,StatusCode.OK,"查询成功",brand);
    }

@ApiImplicitParams 用于描述接口的非对象参数集。
@ApiImplicitParam 用于描述接口的非对象参数，一般与 @ApiImplicitParams 组合使用
很多时候就写name和value属性dataType就可以，其它属性框架可以自己根据我们的代码推导出来

name 参数名字
value 参数意义的描述
requeired是否必填 true必填 fales非必填

paramType查询参数类型：放置参数的位置      取值：
  path：以地址的形式提交数据，根据 id 查询用户的接口就是这种形式传参。
  query：Query string 的方式传参。  ?name=cj&age=17
  header：在请求头中
  form：以 Form 表单的形式提交。

dataType参数的数据类型 Long String

    @GetMapping("/testApi/{page}/{size}")

    @ApiImplicitParams({

            @ApiImplicitParam(name = "page",value = "页码",dataType="Long"),

            @ApiImplicitParam(name = "size",value = "每页条数",dataType="Long"),

            @ApiImplicitParam(name = "name",value = "姓名",dataType="String"),

            @ApiImplicitParam(name = "token",value = "token信息",dataType="String")

    })

    public Result testApi(@PathVariable("page")int page,@PathVariable("size") int size,String name,

                          @RequestHeader(name = "token")String token){

        System.out.println(page);

        System.out.println(size);

        System.out.println(name);

        System.out.println(token);

        return new Result(true,StatusCode.OK,"查询成功","s");

    }

实体类

@ApiModel 可设置接口相关实体的描述。

文档申明

写个配置类即可，注意导包，然后扫描的接口路径别写错

@Configuration

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

public class SwaggerConfig {

    @Bean

    public Docket customDocket() {

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .select()

                .apis(RequestHandlerSelectors.basePackage("com.changgou.service.goods.controller"))

                .build();

    }



    private ApiInfo apiInfo() {

        Contact contact = new Contact("团队名", "http://www.my.com", "my@my.com");

        return new ApiInfoBuilder()

                .title("文档标题")

                .description("文档描述")

                .contact(contact)   // 联系方式

                .version("1.1.0")  // 版本

                .build();

    }

}