走进SpringBoot整合Swagger文档

走进 SpringBoot整合Swagger文档

Swagger简介：

导入jar包

创建SwaggerConfig

部分常用swagger2的注解

1.Swagger简介：在前后端分离的时代，无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档，Swagger的出现即提供了一个规范，解决了这个问题。
**

2.导入jar包

1.引入 Swagger2库

代码如下（swagger2依赖包）：

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

2.创建Swagger2的配置类

package com.lh.x_admin.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2 配置类
 * @Configuration 让 Spring 容器加载该配置类
 * @EnableSwagger2 用于启动 swagger2
 */
@EnableSwagger2
@Component
@Configuration
public class Swagger2Config {
    /**
     * swagger2 启动后，通过createRestApi函数创建Docket的Bean，
     * apiInfo() 用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。
     * select() 函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lh.x_admin.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建API接口文档")
                .description("springbootAPI接口文档")
                .termsOfServiceUrl("http://localhost:8080/")
                .version("1.0")
                .build();
    }
}

3.使用注解描述你的API接口

package com.lh.x_admin.controller;

import com.lh.x_admin.entity.User;
import com.lh.x_admin.service.UserService;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;
import javax.servlet.http.HttpSession;

@RestController
@Api(value = "获取用户数据",tags = "用户登录处理")
public class UserController {
    @Resource
    private UserService userService;

    @PostMapping("/user/doLogin")
    @ApiOperation("用户登录的接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username",value = "用户名"),
            @ApiImplicitParam(name = "password",value = "密码")
    })
    public String doLogin(@RequestParam("username") String username, @RequestParam("password") String password, HttpSession session) throws Exception {
        User user=userService.login(username,password);
        if (user!=null){
            session.setAttribute("loginUser",user);
            return "index";
        }else{
            return "login";
        }
    }
}

4.效果展示

a. 启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html，就能看到浏览器所展示的RESTful API的页面。我们可以再点开具体的API请求，以POST类型的登录请求处理为例，可找到接口中我们配置的一些接口的描述信息以及参数的描述信息

5.部分常用swagger2的注解

@Api() 
用于类；表示标识这个类是swagger的资源 
tags–表示说明 
value–也是说明，可以使用tags替代 
但是tags如果有多个值，会生成多个list

@ApiOperation() 用于方法；表示一个http请求的操作 
value用于方法描述 
notes用于提示内容 
tags可以重新分组（视情况而用） 
@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等） 
name–参数名 
value–参数说明 
required–是否必填

@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收 
value–表示对象名 
description–描述 
都可省略 
@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改 
value–字段说明 
name–重写属性名字 
dataType–重写属性类型 
required–是否必填 
example–举例说明 
hidden–隐藏

@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上 
比较简单, 这里不做举例

@ApiImplicitParam() 用于方法 
表示单独的请求参数 
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam 
name–参数ming 
value–参数说明 
dataType–数据类型 
paramType–参数类型 
example–举例说明