Swagger-快速上手

Swagger

1.1 Swagger是做什么的

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

Swagger能够在线自动生成 RESTFul接口的文档，同时具备测试接口的功能。

简单点来讲就是说，swagger是一款可以根据RESTFul风格生成的生成的接口开发文档，并且支持做测试的一款中间软件。不是RESTFul风格也能生成文档。

特点是在线的，及时的，最新的。

1.2 Swagger优点和作用

· 服务器端只需要定义好接口，会自动生成文档，接口功能、参数一目了然

· 联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位是前端还是后端的问题

· 对于某些没有前端界面UI的功能，可以用它来测试接口

· 操作简单，不用了解具体代码就可以操作

1.3 Swagger动态生成API

首先通过SpringBoot创建Web项目。选择web依赖。

maven的pom.xm.加入swagger依赖

<!--Swagger依赖-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

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

如果使用SpringBoot 2.6以上版本，需要在application.properties加入

# 解决springboot2.6.2使用swagger的问题

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

# 同时我们设置下contentpath
server.servlet.context-path=/ylb

在启动类上加上**@Enableswagger2**

之后便可以在浏览器访问http://localhost:8080/ylb/swagger-ui.html

swagger 修改配置，从而实现修改这个swagger文档头部信息，以及不显示basic-error-controller

package com.yqyang.swaggertest.settings;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;

@Configuration
public class SwaggerConfiguration {
    @Bean
    public Docket docket(){
        // 文档类型 2.0版本
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("盈利宝")
                .version("1.0")
                .description("前后端分离微服务项目")
                .contact( new Contact("yqyang", //文档发布者
                        "http://www.yqyang.com",  //文档发布者网站
                        "463757390@qq.com")) //文档发布者的联系邮箱
                .build();
        docket.apiInfo(apiInfo);
        
        // 指定注解   不显示默认的 basic-error-controller
        docket = docket.select()
                .apis(RequestHandlerSelectors.basePackage("com.yqyang.swaggertest")).build();
        return docket;
    }

}

同时使用国人开发的一款UI

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

同时在启动类添加@EnableSwaggerBootstrapUI

访问地址: http://localhost:8080/ylb/doc.html

1.4 Swagger Api

Swagger中注解列表：

• @Api

  用在类上，说明该类的作用。可以标记一个Controller 类作为 Swagger 文档资源

  例如：

  **@Api(tags={"用户接口"})**
  
  @RestController
  
  public classUserController {
  
  }
  

• @ApiModel

  用在类上，表示对类进行说明，用于实体类中的参数接收说明。

  @ApiModel(value = “com.bjpowernode.AddUserParam”, description = “新增用户参数”)

  public class AddUserParam {

  }

• @ApiModelProperty

  用于字段，表示对 model 属性的说明

  @ApiModel(value = “com.bjpowernode.AddUserParam”, description = “新增用户参数”)

  public classAddUserParam {

  @ApiModelProperty(value = "ID")
  
  privateString id;
  
  @ApiModelProperty(value = "名称")
  
  privateString name;
  
  @ApiModelProperty(value = "年龄")
  
  privateint age;
  

  }

• @ApiOperation

  用在 Controller 里的方法上，说明方法的作用，每一个接口的定义

  ApiOperation(value=“新增用户”, notes=“详细描述”)

  public UserDto addUser( AddUserParam param) {

  }

• @ApiImplicitParam和 @ApiImplicitParams

  用于方法上，为单独的请求参数进行说明

  **@ApiImplicitParams({**
  
  **@ApiImplicitParam(name = "id", value = "用户ID", dataType = "string", paramType ="query", required = true, defaultValue = "1") })**
  
  @GetMapping("/user")
  
  publicUserDto getUser(@RequestParam("id") String id) {
  
  returnnew UserDto();
  
  }
  

• name：参数名，对应方法中单独的参数名称。

• value：参数中文说明。

• required：是否必填。

• paramType：参数类型，取值为 path、query、body、header、form。

• dataType：参数数据类型。

• defaultValue：默认值。

l @ApiResponse 和 @ApiResponses

用于方法上，说明接口响应的一些信息；@ApiResponses组装了一个或多个 @ApiResponse

@ApiResponses({ @ApiResponse(code = 200, message = “OK”,response = UserDto.class) })

@PostMapping(“/user”)

public UserDto addUser(AddUserParam param) {

}