swagger配置使用，springboot配置使用swagger-bootstrap-ui,swagger常用的注解_enableswaggerbootstrapui

springboot配置使用swagger-bootstrap-ui

1、pom依赖

maven的pom文件中引入swagger的相关依赖，这里采用第三方swagger-bootstrap-ui，界面更加友好

 <!-- swagger自动生成API文档支持 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- 引入第三方的swaggerUI -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>
1
2
3
4
5
6
7
8
9
10
11
12

2、注解方式配置Swagger

新建SwaggerConfig.java配置文件
可以配置.apis(RequestHandlerSelectors.basePackage("com.demo.contorller"))扫描包下面的接口
也快可以配置.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))扫描所有java文件中使用了@RestController注解的接口

package com.demo.config;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
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.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger配置
 */
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {

	// 接口文档访问路径：http://域名:端口/doc.html#/  例如： http://localhost:9999/doc.html#/
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.demo.contorller"))  //扫描包
                //.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) //扫描注解
                .paths(PathSelectors.any())
                .build()
                .apiInfo(new ApiInfoBuilder()
                        .title("后台接口api文档")
                        .description("简单描述")
                        .termsOfServiceUrl("www.baidu.com")
                        .version("1.0")
                        .build());
    }

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

然后在Config.java文件中加入配置静态资源映射
反正我是需要加入映射，不然访问的时候访问不到。

package com.demo.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
public class Config extends WebMvcConfigurationSupport {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 配置静态资源映射
        //此处不配置swagger-ui的入口，目的是不使用swagger-ui，而使用第三方UI
        // registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/")S;
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");

        super.addResourceHandlers(registry);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

3、测试访问

访问路径：

http://域名:端口/doc.html#/`
1

例如：

http://localhost:9999/doc.html#/
1

效果图：

题外话：
xml配置貌似是这么写，我还没有试过，下次我试试xml集成swagger-bootstrap-ui：

<!--注入swagger文档配置类-->
<bean id="swaggerConfig" class="cn.drip.## 标题dripblog.config.SwaggerConfig"></bean>

<!--配置swagger-bootstrap-ui访问的静态资源-->
    <mvc:resources mapping="doc.html" location="classpath:/META-INF/resources/"/>
    <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>
1
2
3
4
5
6

swagger常用的注解

1、@API

@Api(tags="测试接口模块")
1

用于类上，生成的api文档会根据tags分类

2、@ApiOperation

使用于在方法上，表示一个http请求的操作
常用属性：
value用于方法描述
notes用于提示内容
tags可以重新分组（视情况而用）

@ApiOperation(value = "添加海报信息")
1

3、@ApiImplicitParams

使用在方法上或者参数上，字段说明；表示对参数的添加元数据（说明或是否必填等）
name–参数名
value–参数说明
dataType -参数类型
required–是否必填

@ApiImplicitParams({
            @ApiImplicitParam(name = "userid", dataType = "String", required = true,value = "当前登录人id")
    })
1
2
3

4、@ApiModel()

使用在类上，表示对类进行说明，用于参数用实体类接收
value–表示对象名
description–描述

@ApiModel("用户实体类")
1

5、@ApiModelProperty()

使用在方法，字段上，表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏

 @ApiModelProperty(value = "个人介绍1",required = true)
1