Swagger在线文档

Swagger

什么 Swagger？

# 定义
   Swagger 是是一款让你更好的书写API文档的框架。用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
   总体目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法、参数和模型紧密集成到服务器的代码，允许Api来始终保持同步
	
# 作用
    1. 接口的文档在线自动生成。
    2. 在线功能测试。不需要像postman一样下载
    
简单说就是
    Swagger 是一种规范。
    springfox-swagger2 是基于 Spring 生态系统的该规范的实现。
    springfox-swagger-ui 是对 swagger-ui 的封装，使其可以使用 Spring 的服务

为什么要使用Swagger？

# Swagger是一款容器平台开放API，对于某些人来说,或许有些陌生,但是对于互联网行业的从业者，不应该陌生,因为Swagger是一款用于管理各个界面的api接口的工具，比如登录接口，查找用户接口，添加用户接口，这些接口都需要通过一款平台或者工具管理。

Swagger 提供了一个全新的维护 API 文档的方式 优点：
1.自动生成文档：只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。
2.跨语言性，支持 40 多种语言。
3.Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。

官网参考

# 项目启动后，访问下面的网址就可以进入到在线文档
http://ip:port/swagger-ui.html

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

# 官网文档 （英文）
http://springfox.github.io/springfox/docs/snapshot/

使用

1.依赖

版本号请根据实际情况自行更改。

第一个是API获取的包，第二是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。       
 <!-- springfox -->
        <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.定义核心配置类

package com.wz.goods.config;

import com.google.common.base.Predicate;
import com.wz.goods.annotation.SwaggerCustomIgnore;
import com.wz.goods.controller.SkuController;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static com.google.common.base.Predicates.not;
import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;
import static springfox.documentation.builders.RequestHandlerSelectors.withMethodAnnotation;

@Configuration   //定义核心配置类
@EnableSwagger2  //定义Swagger文档
@ComponentScan("com.wz.goods.controller")  //扫包   由于是springCloud项目 默认已经扫描
public class SwaggerConfig {
    
    //ioc中存入Docket对象，是文档生成的核心对象，里面配置一些必要的信息
    @Bean
    public Docket swaggerSpringMvcPlugin(){
        //指定规范，这里是SWAGGER_2
        return new Docket(DocumentationType.SWAGGER_2)
                //设定Api文档头信息，这个信息会展示在文档UI的头部位置
                .apiInfo(swaggerDemoApiInfo())
                .select()
                //添加过滤条件，谓词过滤predicate，这里是自定义注解进行过滤
                //该注解是一个自定义注解。不需要写反射类只要有元注解即可生效。
            	//整理时发现Swagger提供了一个可以忽略的注解  @ApiIgnore 用于方法上方
                .apis(not(withMethodAnnotation(SwaggerCustomIgnore.class)))
 //这里配合@ComponentScan一起使用，又再次细化了匹配规则(当然，我们也可以只选择@ComponentScan、paths()方法当中的一中)
            
                //坑！！！！！
                //.paths(allowPaths())
            
                .build(); //构建
    }

    /**
     * 自定义API文档基本信息实体
     * @return
     */
    //定义文档的主页面显示信息
    private ApiInfo swaggerDemoApiInfo(){

        //构建联系实体，在UI界面会显示
        Contact contact = new Contact("性感震哥在线发牌", "http://www.baidu.com", "384914685@qq.com");

        return new ApiInfoBuilder()
                //添加联系人信息
                .contact(contact)
                //文档标题
                .title("Swagger2构建RESTful API文档的测试")
                //文档描述
                .description("SpringBoot集成Springboot畅购项目，键盘敲烂月薪过万")
                //文档版本
                .version("1.1.5")
                //构建
                .build();
    }
    /**
     * path匹配规则
     * @return
     */
    //坑+1
    private Predicate<String> allowPaths(){
        return or(
                regex("/user.*"),
                regex("/role.*")
        );
    }
}

2.自定义注解

此类可以省略，不影响使用

package com.wz.goods.annotation;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

//定义元注解
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface SwaggerCustomIgnore {
}

3.对接接口

@RestController
@RequestMapping("/sku")
@Api(tags = "商品sku接口", description = "提供sku相关的Rest API")
public class SkuController {

    @Autowired
    private SkuService skuService;

    @GetMapping("/{id}")
    @ApiOperation(value = "按sku的id查询sku", notes = "查询单个的时候使用的接口，用result结果对象返回")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "skuID", required = false, paramType = "query"),
            // 在参数中没有，但是也可以显示
            @ApiImplicitParam(name = "code", value = "状态码", required = true, paramType = "query"),
    })
    public Result findById(@PathVariable String id){
        Sku sku = skuService.findById(id);
        return new Result(true,StatusCode.OK,"查询成功",sku);
    }

    @GetMapping("/spu/{spuId}")
    @ApiOperation("按照Spu的id查询其下的所有Sku")
    public List<Sku> findSkuListBySpuId(@PathVariable(value = "spuId") String spuId){
        HashMap<String,Object> searchMap = new HashMap<>();

        //判断，不是不是all关键字，则将pid装入map
        if (!"all".equals(spuId)){
            searchMap.put("spuId",spuId);
        }

        searchMap.put("static","1"); //设置状态

        //按照map条件查询
        //如果为all  那么就是空， 会穿透 查询所有sku
        List<Sku> skuList = skuService.findList(searchMap);

        return skuList;
    }

//  @SwaggerCustomIgnore //定义此注解 那么就不会识别该接口方法
    @ApiIgnore
    @PostMapping
    public String swaggerTest(){
        return "";
    }
}

4.常用注解

接下来将swagger2的核心 就是使用注解给接口和每个方法加说明

    @Api：修饰整个类，描述Controller的作用
    @ApiOperation：描述一个类的一个方法，或者说一个接口
    @ApiParam：单个参数描述
    @ApiModel：用对象来接收参数
    @ApiProperty：用对象接收参数时，描述对象的一个字段
    @ApiResponse：HTTP响应其中1个描述
    @ApiResponses：HTTP响应整体描述
    @ApiIgnore：使用该注解忽略这个API
    @ApiError ：发生错误返回的信息
    @ApiImplicitParam：一个请求参数
    @ApiImplicitParams：多个请求参数