在项目中使用Swagger接口说明

目录

1 Swagger介绍

1.1 Swagger应用场景

1.2 Swagger作用

2 Swagger注解说明

3 在项目中使用Swagger

---

1 Swagger介绍

Swagger是最流行的API开发工具，它遵循OpenAPI Specification（OpenAPI规范，简称OAS）。Swagger可以贯穿于整个API生态，如API的设计、编写API文档、测试和部署。

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

1.1 Swagger应用场景

1. 如果你的RESTful API接口都开发完成了，可以用Swagger-editor来编写API 文档（yaml文件或json文件），然后通过Swagger-ui来渲染该文件，展现API文档。
2. 如果你的RESTful API还未开始，也可以使用Swagger生态，来设计和规范你的API，以Annotation（注解）的方式给你的源代码添加额外的元数据。这样Swagger就可以检测到这些元数据，自动生成对应的API描述信息。Swagger 支持自动生成 API 文档。

1.2 Swagger作用

1. 接口的文档在线自动生成。
2. 功能测试。

2 Swagger注解说明

（1）@Api：用在类上，说明该类的作用。

（2）@ApiOperation：给API增加方法说明。

（3）@ApiImplicitParams : 用在方法上包含多个参数说明。

（4）@ApiImplicitParam：用在方法上包含一个参数说明。

1. paramType：指定参数放在哪个地方。
2. name：参数名
3. dataType：参数类型
4. required：参数是否必须传
5. value：说明参数
6. defaultValue：参数的默认值

注：paramType类型

• header：请求参数放置于Request Header，使用@RequestHeader 获取。
• query：请求参数放置于请求地址，使用@RequestParam获取
• path：用于restful接口。
• @PathVariable：获取请求参数。
• body
• form

（5）@ApiResponses：用于表示一组响应。

（6）@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息。

• code：数字，例如400。
• message：信息，例如"请求参数没填好"。
• response：抛出异常的类   。

（7）@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）。

（8）@ApiModelProperty：描述一个model的属性。

3 在项目中使用Swagger

（1）在pom.xml中添加Swagger依赖

<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency>

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

（2）创建Swagger配置类，与Application.java同级目录

package org.springboot;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.annotations.ApiOperation;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


//加载该类配置
@Configuration
//启用Swagger2
@EnableSwagger2
public class SwaggerConfig {

    /*
    * 创建API应用
    * */
    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .build();
    }

}

（3）在接口类上添加@Api注解

（4）在接口方法上添加@ApiOperation注解

（5）传递一个对象参数。在后台采用对象接收参数时，Swagger自带的工具采用的是JSON传参，测试时需要在参数上加入@RequestBody，正常运行采用form或URL提交的时候需要删除。

（6）传递单个参数

（7）运行项目后打开http://localhost:8080/swagger-ui.html

（8）进行功能测试

（9）Swagger以json格式进行传参

（10）在Swagger配置类创建API应用时，通过host()方法指定测试时的主机名，如果没有指定就是当前主机，可以指定端口