springboot 中配置Swagger及其扩展

1.引入依赖

        <!--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.创建swagger配置类

如图：

 

配置类代码（复制即可）：

 
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
import java.util.ArrayList;
import java.util.List;
 
@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    private String title = "项目标题";
 
    private String description = "项目标题-描述";
 
    private String version = "项目版本";
    
    private String basePackage = "xyz.ark.backstage_12.controller";
 
    //控制swagger是否启动开发模式 测试模式 生产模式
    @Value("${swagger2.enable}")
    private boolean enable;
 
    //指定是否需要给所有接口添加头部信息
    private boolean header = false;
 
    @Bean
    public Docket createRestApi() {
        List<Parameter> pars = header == true ? addParameters() : null;
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars)
                .enable(enable);
    }
 
    /**
     * 为swagger接口的时候添加头部信息
     * 如何有多个头部信息 可以add()直接添加到pars就可以了
     *
     * @return
     */
    private List<Parameter> addParameters() {
        List<Parameter> pars = new ArrayList<Parameter>();
        ParameterBuilder tokenPar = new ParameterBuilder();
        tokenPar.name("token").description("(模拟token传入)非必填 header").modelRef(new ModelRef("string")).parameterType("header").required(false);
 
        //添加一个tokne 用于认证用户本读是否存在token
        pars.add(tokenPar.build());
        return pars;
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl("")
                .version(version)
                .build();
    }
}

 

 

3.给实体类上面添加参数描述

@ApiModelProperty(value = "用户ID")

value参数：用来指定参数描述

如图：

 

 

4.controller层添加如下注解描述即可

如图：

上图代码：

package xyz.ark.backstage_12.controller;
 
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import xyz.ark.backstage_12.entity.Result;
import xyz.ark.backstage_12.entity.User;
import xyz.ark.backstage_12.service.UserService;
 
import java.util.List;
 
@RestController
@Api(tags = "用户操作模块")
public class UserController {
 
    @Autowired
    UserService userService;
 
    @GetMapping("/users")
    @ApiOperation(value = "获取所有用户的信息")
    public Result selectUser() {
        List<User> user = userService.selectUsers();
        return user.size() > 0 ? Result.ok(user) : Result.ok("数据库无数据");
    }
 
    @GetMapping("/user/{id}")
    @ApiOperation(value = "根据用户ID获取用户的信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "Authorization" , value = "认证Tonken" , required = true , dataType = "string" , paramType = "header"),
            @ApiImplicitParam(name = "id" , value = "用户id" ,dataType = "string" , required = true , paramType = "query")
    })
    public Result selectUserById(@PathVariable("id") int id) {
        User user = userService.selectUserById(id);
        return Result.ok(user);
    }
 
    @PutMapping("/user")
    @ApiOperation(value = "根据用户ID修改用户信息")
    public Result updataUserById( User user) {
        int i = userService.updateUserById(user);
        return i > 0 ? Result.ok("更新成功") : Result.ok("更新失败");
    }
 
    @PostMapping("/user")
    @ApiOperation(value = "添加新的用户")
    public Result installUser(User user) {
        int i = userService.installUser(user);
        if (i > 0) {
            return Result.ok("添加成功");
        }
        return Result.ok("添加失败");
    }
 
    @DeleteMapping("/user/{id}")
    @ApiOperation(value = "根据用户ID删除用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "Authorization" , value = "认证Tonken" , required = true , dataType = "string" , paramType = "header"),
            @ApiImplicitParam(name = "用户ID" , value = "用户id" ,dataType = "string" , required = true , paramType = "query")
    })
    public Result deleteUserById(@PathVariable("id") int id) {
        int i = userService.deleteUserById(id);
        return i > 0 ? Result.ok("删除成功") : Result.ok("删除失败");
    }
}

 

操作完成后 访问   http://localhost:8080/swagger-ui.html

 

4.swagger扩展文档

 

 

 

 

想要将第二个swagger-ui页面变成 图一的效果 只需要在 ， pom文件中 swagger的两个依赖之后 在添加一个 如下两个依赖即可

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-bean-validators</artifactId>
            <version>2.9.2</version>
        </dependency>

 

此时你的项目可以访问 http://localhost:8080/doc.html 即可看到图一效果，http://localhost:8080/swagger-ui.html可访问图二效果。

其他配置不变。

 

此时 只需要 在 当前的pom文件中添加两个依赖即可。