05-Swagger2介绍、springboot集成Swagger2

1、swagger2介绍

1.1、什么是swagger2

        编写和维护接口文档是每个程序员的职责，根据Swagger2可以快速帮助我们编写最新的API接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。

1.2、常用注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回的信息等等。

control层使用的：

    @Api：修饰整个类，描述Controller的作用

    @ApiOperation：描述一个类的一个方法，或者说一个接口

    @ApiParam：单个参数描述

实体类使用的:

    @ApiModel：用对象来接收参数

    @ApiModelProperty：用对象接收参数时，描述对象的一个字段

    @ApiImplicitParam：一个请求参数

    @ApiImplicitParams：多个请求参数

2、springboot集成Swagger2

1、pom.xml引入依赖

    <properties>

        <swagger.version>2.7.0</swagger.version>

    </properties>       

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>

        <!--swagger ui-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

2、添加swagger2配置类

package com.wei.config;

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

/**
 * Swagger2配置信息
 *
 * @author nikoword
 */

//配置类
@Configuration
//开启Swagger
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                //只显示api路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();
    }

    @Bean
    public Docket adminApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                //只显示admin路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();
    }

    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("作业网站-API文档")
                .description("本文档描述了作业网站微服务接口定义")
                .version("1.0")
                .contact(new Contact("nikoword", "http://www.com", "nikoword0411@gmail.com"))
                .build();
    }

    private ApiInfo adminApiInfo(){

        return new ApiInfoBuilder()
                .title("作业后台管理系统-API文档")
                .description("本文档描述了作业后台管理系统微服务接口定义")
                .version("1.0")
                .contact(new Contact("nikoword", "http://www.com", "nikoword0411@gmail.com"))
                .build();
    }


}

3、springboot启动类加载SwaggerConfig的目录

//开启SpringBoot
@SpringBootApplication

//扫描swagger配置类的目录
@ComponentScan(basePackages = "com.wei.config")
public class ControllerApplication {

    public static void main(String[] args) {
        SpringApplication.run(ControllerApplication.class,args);
        System.out.println("controller模块启动了！！！");
    }

}

4、使用swagger2测试

localhost:8080/swagger-ui.html