SpringBoot集成Swagger2

官网：https://swagger.io/

本文基于SpringBoot项目集成Swagger

    org.springframework.boot
    spring-boot-starter-web


    org.springframework.boot
    spring-boot-starter-test
    test



    io.springfox
    springfox-swagger2
    2.9.2



    io.springfox
    springfox-swagger-ui
    2.9.2

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

@RestController
public class HelloController {

    @RequestMapping(value = "/hello")
    public String helloWorld() {
        return "hello world";
    }
}

启动项目访问http://localhost:8080/swagger-ui.html

从上到下依次是：Swagger信息，Controller接口信息，Models实体类信息

注入Swagger相关配置Bean ——docket

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        return new Docket(documentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("两米以下皆凡人", "https://blog.csdn.net/qq_43509535", "penghuanzhi@pwrd.com");
        return new ApiInfo(
                // 标题
                "彭焕智的Swagger2入门教程",
                // 描述
                "学习演示如何配置Swagger",
                // 版本
                "v1.0",
                // 组织链接
                "http://terms.service.url/组织链接",
                // 联系人信息
                contact,
                // 许可
                "Apatch 2.0 许可",
                // 许可连接
                "许可链接",
                // 扩展
                new ArrayList<>()
        );
    }
}

测试

从上图可以发现，在不配置扫描位置的情况下，默认会把error请求也给显示出来了，Models中还会把ModelAndView和View两个实体Bean也给加载出来，这对于我们来说是不需要的，所以可以配置扫描位置将其过滤出来

@Bean
public Docket docket() {
    return new Docket(documentationType.SWAGGER_2)
        //默认开启，如果不需要Swagger接口文档，就传入false
        .enable(true)
        .apiInfo(apiInfo())
        // 通过select()方法，去配置扫描接口
        .select()
        // RequestHandlerSelectors配置如何扫描接口
        // basePackage:指定要扫描的包
        // any():扫描全部
        // none():不扫描
        // withClassAnnotation:扫描类上的注解，参数是一个注解的反射对象，比如：RestController.class
        // withMethodAnnotation:扫描方法上的注解，比如：GetMapping.class
        .apis(RequestHandlerSelectors.basePackage("com.phz.swagger.controller"))
        // 配置如何通过path过滤,即这里只扫描请求以hello开头的请求，比如hello/world
        .paths(PathSelectors.ant("/hello
public class User {
    private String name;
    private String password;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

@PostMapping(value = "/user")
public User user(){
    return new User();
}

这样配置也可以，但是一个model复杂了以后，就看着比较麻烦了，所以还可以进一步配置，给model以及model各个属性加上描述

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    private String name;
    @ApiModelProperty("密码")
    private String password;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

给Controller加上描述

@Api(tags = "hello控制器")
@RestController
public class HelloController {

@ApiOperation("Hello请求")
@GetMapping(value = "/hello")
public String helloWorld() {
    return "hello world";
}

@ApiOperation("登录请求")
@PostMapping(value = "/login")
public void login(@ApiParam("用户名") String username, @ApiParam("密码") String password) {
    System.out.println("登录成功");
}