Swagger2的使用

1. 引入依赖

1.1 父工程引入依赖

注意: 是追加到原来的父工程里面

   <properties>
        <swagger.version>2.9.2</swagger.version>
        <swagger-bootstrap-ui.version>1.9.2</swagger-bootstrap-ui.version>
    </properties>

<dependencyManagement>
        <dependencies>
            <!--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>
            <!--swagger-bootstrap-ui-->
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>swagger-bootstrap-ui</artifactId>
                <version>${swagger-bootstrap-ui.version}</version>
            </dependency>
        </dependencies>
    </dependencyManagement>

1.2 子工程引入依赖

一般这个子工程是公共模块，比如我这里的service-base模块

注意: 是追加到原来的子工程里面

    <dependencies>
        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        </dependency>
        <!--swagger ui-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
        </dependency>
    </dependencies>

2. 配置类

注意：当前这个包必须被其他模块扫描到，比如@ComponentScan({"com.zmj.srb"})

package com.zmj.srb.base.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket adminApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();
    }
    private ApiInfo adminApiInfo() {
        return new ApiInfoBuilder().title("SRB后台管理系统API文档")
                .description("本文档描述了SRB后台管理系统各个模块的接口调用方式")
                .version("1.6")
                .contact(new Contact("朱梦君","http://dreams.com","dream98job@126.com"))
                .build();
    }
    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();
    }
    private ApiInfo webApiInfo() {
        return new ApiInfoBuilder().title("SRB网站API文档")
                .description("本文档描述了SRB网站各个模块的接口调用方式")
                .version("1.6")
                .contact(new Contact("朱梦君","http://dreams.com","dream98job@126.com"))
                .build();
    }
}

启动service-core模块

package com.zmj.srb.core;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;

@SpringBootApplication
@ComponentScan({"com.zmj.srb"})
public class ServiceCoreApplication {

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

访问地址是 http://IP:port/swagger-ui.html

比如：   http://localhost:8110/swagger-ui.html

3.Controller层的注解 

• @Api：描述API接口的基本信息，包括接口名称、描述、作者等。
• @ApiOperation：描述API接口的操作方法，包括HTTP请求方法、接口路径、接口说明等。
• @ApiParam：描述API接口的参数信息，包括参数名称、参数类型、参数说明等

4.实体类上的注解

• @ApiModel：描述API接口的返回结果类型，包括返回结果的数据结构、返回结果的说明等。
• @ApiModelProperty：描述API接口返回结果的属性信息，包括属性名称、属性类型、属性说明等

 

5.分组 

6.文档描述