1. Swagger的概述

    Marty Pitt编写了一个基于Spring的组件swagger-springmvc。Spring-fox就是根据这个项目发展而来的全新项目

Spring-fox的作用：

• 根据代码生成接口文档，所以在正常进行更新项目时，修改代码即可，它会实时进行生成
• 利用自身AOP特性，把Swagger集成进来，底层还是Swagger。但是使用起来方便很多

在实际的开发中，都是Spring-for配合Swagger进行文档开发

2. Swagger初体验

① 通过Spring Initializr构建一个SpringBoot项目

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

@SpringBootApplication
@EnableSwagger2 //EnableSwagger2是springfox提供的一个注解，代表swagger2相关技术开启。它会扫描当前类所在包及其子包中所有类型注解
public class springapplication {

    public static void main(String[] args) {
        SpringApplication.run(springapplication.class,args);
    }
}

@RestController
public class swaggertest {

    @GetMapping("/getswagger")
    public String getswagger(String user, Integer password){


        return "Get Mothed Swagger";
    }

    @PostMapping("/postswagger")
    public String postswagger(){


        return "Post Mothed Swagger";
    }

    @RequestMapping("mothedswagger")
    public String mothedswagger(){


        return "Mothed Swagger";
    }
}

3. Swagger的常用配置

Swagger配置依赖Decket

3.1 基本信息配置

基本信息配置使用ApiInfo对象进行配置

ApiInfo的方法：

• contact：设置作者信息
• title：设置标题
• description：描述信息
• version：版本
• license：协议
• licenseUrl：协议地址
• termsOfServiceUrl：服务的条款

例：

@Bean
public Docket docket(){
    //创建一个Docket对象，参数：文件类，这里使用SWAGGER_2类型文档
    Docket docket = new Docket(DocumentationType.SWAGGER_2);
    //API帮助文档的描述信息对象
    ApiInfo apiInfo = new ApiInfoBuilder()
            .contact(//发布者信息
                    new Contact("空想家",//文档发布者名称
                            "https://wql.luoqin.ltd",//文档发布者地址或者企业网站
                            "2562694007@qq.com"))//文档发布者邮箱
            .title("Swagger框架学习帮助文档")//文档发布的标题
            .description("Swagger框架学习帮助文档详细描述 -- Swagger是一个由于开发RestAPI帮助文档的框架")//文档描述
            .version("1.1")//文档发布的版本
            .termsOfServiceUrl()
            .build();
    docket.apiInfo(apiInfo);//将基础信息加入Docket
    return docket;
}

3.2 扫描包配置

扫描包：扫描哪些包下的注解生成接口文档，一种更精细化的操作

该配置使用到docket对象的两个方法：

1. select()：获取docket的选择器，返回ApiSelectorBuilder
2. apis()：设置扫描那个包

例：

@Bean
public Docket docket(){
    Docket docket = new Docket(DocumentationType.SWAGGER_2);

    docket.select()
            .apis(RequestHandlerSelectors.basePackage("com.swg.controller")).build();

    return docket;
}

3.3 路径服务配置

路径服务的含义：规定哪些Url地址范围可以生成接口文档

该配置使用到docket对象的两个方法：

1. select()：获取docket的选择器，返回ApiSelectorBuilder
2. paths()：设置地址匹配规则

例：

@Bean
public Docket docket(){

    Docket docket = new Docket(DocumentationType.SWAGGER_2);
    docket.select()
            .apis(RequestHandlerSelectors.basePackage("com.swg.controller"))
            //PathSelectors.regex正则表达式路径匹配
            .paths(PathSelectors.regex("/swaggerwql/.*")).build();//请求url以/swaggerwql开头的才进行匹配

    return docket;
}