进阶SpringBoot之 Swagger 分组与接口注释

配置 API 文档分组：

只需在 SwaggerConfig 配置类下 Docket 添加一行 groupName()

代码如下：

package com.demo.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.builders.PathSelectors;
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;

import java.util.ArrayList;

import static springfox.documentation.service.ApiInfo.DEFAULT_CONTACT;

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {

    //配置Swagger的Docket的bean实例
    @Bean
    public Docket docket(Environment environment){

        //设置要显示的Swagger环境
        Profiles profiles = Profiles.of("dev", "test");
        //通过判断是否处于设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("demo")  //分组
                //.enable(false)   //enable决定是否启动Swagger，如果为false，则Swagger不能在浏览器中访问
                .enable(flag)
                .select()
                /*
                RequestHandlerSelectors：配置要扫描接口的方式
                basePackage：指定要扫描的包
                RequestHandlerSelectors.any()：扫描全部
                RequestHandlerSelectors.none()：不扫描
                RequestHandlerSelectors.withClassAnnotation(RestController.class)：扫描类上的注解
                RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)：扫描方法上的注解
                 */
                .apis(RequestHandlerSelectors.basePackage("com.demo.swagger.controller"))
                .paths(PathSelectors.ant("/demo/**"))  //paths：过滤的路径
                .build();
    }

    //配置Swagger信息apiInfo
    private ApiInfo apiInfo(){
        //作者信息
        //Contact contact = new Contact("name","url","email");
        return new ApiInfo("Api Documentation",
                "Api Documentation",
                "1.0",
                "urn:tos",
                DEFAULT_CONTACT,   //contact
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        ); //从ApiInfo源码获取，可以任意修改，展示的前端页面就会显示修改后的页面
    }
}

效果如下：实现文档分组

上述只是配置一个分组，而在复杂环境中，需要配置多个分组

配置多个分组：

只需多个 Docket 实例即可

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

效果如下：

pojo 包下新建 User 类：

文档注释：

@ApiModel 用于 Model 实体类

@ApiModelProperty 用于字段

package com.demo.swagger.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    public String username;

    @ApiModelProperty("密码")
    public String password;
}

controller 包下 HelloController 类的方法需具体到 Get、Post 请求

@Api(tags = "Hello控制器")  放在类上

接口中也提供了 @ApiOperation 文档注解，放在方法上

@ApiParam("用户名")  放在方法括号里

package com.demo.swagger.controller;

import com.demo.swagger.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "Hello控制器")
@RestController
public class HelloController {
    @GetMapping(value = "/hello")
    public String hello(){
        return "hello";
    }

    //只要接口返回值中存在实体类，就会被扫描到Swagger中
    @PostMapping(value = "/user")
    public User user(){
        return new User();
    }

    //Operation接口，放在方法上
    @ApiOperation("Hello控制类")
    @GetMapping(value = "/test")
    public String test(@ApiParam("用户名") String username){
        return "hello"+username;
    }

    @ApiOperation("Post测试")
    @PostMapping(value = "/post")
    public User post(@ApiParam("用户名") User user){
        return user;
    }
}

效果如下：

文档注释成功！

可以在 Swagger 上随意测试填写信息

点击执行，响应信息

如果代码有错误的情况

    @ApiOperation("Post测试")
    @PostMapping(value = "/post")
    public User post(@ApiParam("用户名") User user){
        int i = 2/0;  //被除数不能为0
        return user;
    }

点击执行后就会报 500 错误

"status": 500

"error": "Internal Server Error"

总结：

1.可以通过 Swagger 给一些比较难理解的属性或接口增加注释信息

2.接口文档实时更新

3.可以在线测试

注意：在正式发布时，关闭 Swagger