介绍

什么是Swagger

一个用于生成Restful风格接口文档的规范性框架。

作用

• 用于接口文档的生成
• 用于接口的测试

Spring Boot整合Swagger

引入相关依赖

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

使用

配置类

/**
 * Swagger2配置类
 * 在与spring boot集成时，放在与Application.java同级的目录下。
 * 或者通过 @Import 导入配置
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.turbo.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("")
                .termsOfServiceUrl("")
                .contact("zou", "", "zouxq412@foxmail.com")
                .version("1.0")
                .build();
    }
}

注解

@Api

类注解，用在Controller上，将Controller标注为一个Swagger资源。包含以下几个重要属性：

• tags：API分组标签。相同标签的API会被归类在一组内展示。
• value：如果没有设置tags，value作为tags使用。
• description：用于描述API的功能。

@ApiOperation

用于路由上，对一个操作或者HTTP方法进行描述。具有相同路径的不同操作会被归为一个操作对象。包含以下几个重要属性：

• value：对操作进行简单的描述。
• notes：对操作的详细说明。
• httpMethod：HTTP请求的动作名，包括7种HTTP方法。
• code：默认200，必须符合HTTP状态码规范。

@ApiParam、@ApiImplicitParams和@ApiImplicitParam

用于说明参数请求参数信息。包含以下几个重要属性：

• dataType：参数类型。
• name： 参数名。
• required：是否必传参数，默认false。
• value：参数说明。

@ApiModel和@ApiModelProperty

当接⼝参数和返回值为对象类型时，在实体类中添加注解说明。包含以下几个重要属性：

• value：model的别名，默认为类名。
• description：model的详细描述。

Swagger BootStrap UI

依赖引入

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

参考博文：juejin.cn/post/684490…

作者：TurboSnail