Swagger-UI API文档生产工具基本介绍

基础入门

导入依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

配置

只要controller中接口的返回值中存在实体类，就会被扫描到Swagger的Model中

Swagger对生成API文档的范围有三种不同的选择

• 生成指定包下面的类的API文档
• 生成有指定注解的类的API文档
• 生成有指定注解的方法的API文档

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //配置多个分组，返回多个Docket实例即可
    
    public Docket docket(Environment environment){
        //设置要显示Swagger的环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptProfiles判断当前项目所处的环境
        boolean boo = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //enable是否启动swagger
                .enable(boo)
                .select()
                //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("com.hzb.controller"))
                //为有@Api注解的Controller生成API文档
//                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //.paths(PathSelectors.ant("/sys/**"))
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Binboy")
                .version("v1.0")
                .contact("bin,648164883@qq.com")
                .description("swagger api")
                .build();
    }
}

实体类注解

@ApiModel 注解用于实体类，表示对类进行说明，用于参数用实体类接收。

@ApiModelProperty 注解用于类中属性，表示对 model 属性的说明或者数据操作更改。

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

Controller相关注解

@Api 注解用于类上，表示标识这个类是 swagger 的资源。

@ApiOperation 注解用于方法，表示一个 http 请求的操作。

@ApiParam 注解用于参数上，用来标明参数信息。

@RestController 
@RequestMapping("/swagger") 
@Api(value = "Swagger2 在线接口文档") 
public class TestController {
    @GetMapping("/get/{id}")    
    @ApiOperation(value = "根据用户唯一标识获取用户信息")    
    public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {        
        // 模拟数据库中根据id获取User信息        
        User user = new User(id, "倪升武", "123456");        
        return new JsonResult(user);    
    } 
}

总结：

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

接口文档实时更新

可以在线测试

在正式发布时，关闭Swagger

项目应用

SwaggerProperties

@Data
@EqualsAndHashCode(callSuper = false)
@Builder
public class SwaggerProperties {
    /**
     * API文档生成基础路径
     */
    private String apiBasePackage;
    /**
     * 是否要启用登录认证
     */
    private boolean enableSecurity;
    /**
     * 文档标题
     */
    private String title;
    /**
     * 文档描述
     */
    private String description;
    /**
     * 文档版本
     */
    private String version;
    /**
     * 文档联系人姓名
     */
    private String contactName;
    /**
     * 文档联系人网址
     */
    private String contactUrl;
    /**
     * 文档联系人邮箱
     */
    private String contactEmail;
}

SecurityScheme : 这用于描述我们的API如何保护（基本认证，OAuth2，…）

Security Context：定义一个安全上下文

public abstract class BaseSwaggerConfig {
    public Docket docket(Environment environment){
        SwaggerProperties swaggerProperties = swaggerProperties();
        //设置要显示Swagger的环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptProfiles判断当前项目所处的环境
        boolean boo = environment.acceptsProfiles(profiles);
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                            .apiInfo(apiInfo(swaggerProperties))
                            .select()
                            .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getApiBasePackage()))
                            .paths(PathSelectors.any())
                            .build();
        if (swaggerProperties.isEnableSecurity()) {
            docket.securitySchemes(securitySchemes()).securityContexts(securityContexts());
        }
        return docket;
    }

    public ApiInfo apiInfo(SwaggerProperties swaggerProperties){
        return new ApiInfoBuilder()
                .title(swaggerProperties.getTitle())
                .description(swaggerProperties.getDescription())
                .contact(new Contact(swaggerProperties.getContactName(), swaggerProperties.getContactUrl(), swaggerProperties.getContactEmail()))
                .version(swaggerProperties.getVersion())
                .build();
    }

    private List<ApiKey> securitySchemes(){
        List<ApiKey> result = new ArrayList<>();
        ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");
        result.add(apiKey);
        return result;
    }

    private List<SecurityContext> securityContexts(){
        List<SecurityContext> result = new ArrayList<>();
        result.add(getContextByPath("/*/.*"));
        return result;
    }

    private SecurityContext getContextByPath(String pathRegex) {
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex(pathRegex))
                .build();
    }

    private List<SecurityReference> defaultAuth() {
        List<SecurityReference> result = new ArrayList<>();
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        result.add(new SecurityReference("Authorization", authorizationScopes));
        return result;
    }

    //自定义Swagger配置
    public abstract SwaggerProperties swaggerProperties();
}

SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig extends BaseSwaggerConfig {
    @Override
    public SwaggerProperties swaggerProperties() {
        return SwaggerProperties.builder()
                .apiBasePackage("com.hzb.controller")
                .title("mall后台系统")
                .description("mall后台相关接口文档")
                .contactName("binboy")
                .version("1.0")
                .enableSecurity(true)
                .build();
    }
}