java 整合 swagger-ui 步骤

1.在xml 中添加Swagger 相关依赖

		<!-- springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
1
2
3
4
5
6
7
8
9
10
11
12

2.配置Swagger

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;


@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /*
     * 1.配置生成的文档信息
     * 2.配置生成规则
     * */

    //Docket封装接口文档信息
    @Bean
    public Docket
    getDocket(){

        //创建封面信息对象
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
        apiInfoBuilder.title("《xx项目》接口说明")
                .description("此文档详细说明了xxx项目接口规范")
                .version("v 0.0.1")
                .contact(new Contact("","",""));
        ApiInfo apiInfo = apiInfoBuilder.build();

        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxxxxx.controller"))
                .build();

        return docket;
    }

}

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
39
40
41
42
43

3.启动项目，访问 Swagger UI
访问地址：http://localhost:xxx/swagger-ui.html出现下面界面则配置成功

4.更改界面风格
4.1 添加依赖

 		<dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>
1
2
3
4
5

4.2 启动项目，并访问
访问地址：http://localhost:xxxx/doc.html
4.3效果

5.Swagger 注解

常用的注解
@API类注解，在控制器类添加此注解，可以对控制器类进行功能说明
示例：@Api(value = "提供xx相关接口",tags = "xx管理")

@ApiOperation是用于构建Api文档的注解，它用于标识一个HTTP请求的方法，并描述该方法的作用、请求方式、响应等信息。
@ApiOperation(value = "XXXX接口", httpMethod = "POST", notes = "XXXXXX")

@ApiModelProperty：用于定义API模型的字段，包括字段名、描述、类型等信息。
@ApiModelProperty(value = "xxxx",required = true,example = "xxxx")//required = true 表示该字段为必填字段，example 表示:示例xxx

@ApiIgnore 注解的主要作用是忽略特定的类、方法或方法参数，使其在 Swagger 生成的 API 文档中不显示。
用法：
	@ApiIgnore 注解可以应用于以下三个方面：
	类：当应用于类时，整个类将被忽略，不会在 Swagger 生成的 API 文档中显示。
	方法：当应用于方法时，该方法将被忽略，不会在 Swagger 生成的 API 文档中显示。
	参数：当应用于方法参数时，该参数将被忽略，不会在 Swagger 生成的 API 文档的参数列表中显示。
@ApiParam：用于描述单个入参。可以指定参数的名称、类型、是否必填以及描述信息。
用法：
	@ApiParam(name = "id", type = "integer", required = true, value = "The ID of the resource")
@RequestBody：用于描述整个请求体。可以指定请求体的类型以及是否必填。
用法：
	@RequestBody @ApiParam(name = "requestBody", type = "object", required = true, value = "The request body")
@RequestParam：用于描述URL中的查询参数。可以指定参数的名称、类型、是否必填以及描述信息。
用法：
	@RequestParam(name = "id", type = "integer", required = true, value = "The ID of the resource")
@PathVariable：用于描述URL中的路径参数。可以指定参数的名称、类型、是否必填以及描述信息。
用法：
	@PathVariable(name = "id", type = "integer", required = true, value = "The ID of the resource") 
@RequestHeader：用于描述请求头中的参数。可以指定参数的名称、类型、是否必填以及描述信息。
用法：
	@RequestHeader(name = "Authorization", type = "string", required = true, value = "The authorization token")

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

6.遇见的问题

@ApiModelProperty(value = "xxxx",example = "xxxx")
变量上添加了注解 但是不起作用原因：
1.属性名或属性值不符合规范。例如，属性名应该遵循驼峰命名法，且第二个字母不能大写。另外，对于Boolean类型的字段，字段名应该以is开头。(我遇见的是变量命名不规范导致的)
2.在Controller接口层，需要直接返回使用@ApiModel注解的实体类，或者集合-泛型为使用@ApiModel注解的实体类。
1
2
3
4