使用swagger管理接口

简介：Swagger是一种Rest API的 简单但强大的表示方式，标准的，语言无关，这种 表示方式不但人可读，而且机器可读。 可以作为Rest API的交互式文档，也可以作为Rest API的形式化的接口描述，生成客户端和服务端的代码。

 

下面结合比较常见的场景，大概说下在Springboot下如何使用swagger来管理接口，以便前后端开发人员能够很好的做接口的对接，同时也利于接口的后续维护开发。

 

1. maven里引入swagger所需jar包：

<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger2.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger2.version}</version>
        </dependency>
    </dependencies>

 

2.指定swagger的一些静态资源文件配置，一般用一个类来管理维护：

@Configuration
@EnableSwagger2
public class SwaggerConfiguration extends WebMvcConfigurerAdapter {

    @Value("${swagger2.basePackage:com.xxx}")
    private String swagger2BasePackage;
    @Value("${swagger2.title:系统API文档}")
    private String swagger2Title;
    @Value("${swagger2.api.version:1.0}")
    private String apiVersion;

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars*").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select().apis(RequestHandlerSelectors.basePackage(swagger2BasePackage))
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title(swagger2Title).version(apiVersion).build();
    }
}

 

3. 如何使用？

这一步我会用比较常见的业务场景去描述接口：

首先Controller层（类）上需要这样注解：

@Api(value = "SWAGGER接口")
@RestController
@RequestMapping(value = "/api/swagger/user")
public class SwaggerController{
  //....
}

 

1）请求参数对应一组String字符串或者一个VO，返回结果是单个对象

此时方法一定要有返回而不能是void

eg：根据输入条件查询某条记录

@ApiOperation(value="获取用户详细信息", notes="根据参数来获取用户详细信息")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "用户ID", dataType = "Long", paramType = "query"),
        @ApiImplicitParam(name = "name", value = "用户名字", required = true, dataType = "String", paramType = "query"),
        @ApiImplicitParam(name = "age", value = "用户年龄", dataType = "Long", paramType = "query")
    })
    @RequestMapping(value="", method=RequestMethod.GET)
    @PostMapping("/find1")
    public  User find (@ModelAttribute User user) {//@ModelAttribute User user 等效于Long id, String name; Long age;
        return new User();
    }

 其中User类如下：

//@ApiModel(value="User", description="用户对象")
public class User {
  @ApiModelProperty(value = "用户ID", required = true)
    private Long id;
  @ApiModelProperty(hidden = true)
    private String name;
  @ApiModelProperty(value = "用户年龄")
    private Long age;
  public void setId(Long id) {
    this.id = id;
  }
  public void setName(String name) {
    this.name = name;
  }
  public void setAge(Long age) {
    this.age = age;
  }
  public Long getId() {
    return id;
  }
  public String getName() {
    return name;
  }
  public Long getAge() {
    return age;
  }
    
}

 User类是对应查询条件或查询结果组成的实体~，每个属性需要用@ApiModelProperty去描述每个字段的含义；User类上的@ApiModel注解可以选择性给出。

 

访问swagger接口描述页面只需启动项目（这里是springboot），然后输入http://localhost:8080/swagger-ui.html#!即可访问，我们点击对应的Controller和接口，可以看到：

 

Paramters就是描述输入参数的区域，而Response则是输出的描述，Response可以切换到Model，可以看到输出的字段的具体含义：

 

2）请求参数是复合的，这时候必须对应一个实体类，如：

//@ApiModel(value="Params", description="传入参数")
public class Params {
  @ApiModelProperty(name="param1", value = "参数1", required = true)
  private String param1;
  
  @ApiModelProperty(name="input", value = "输入", required = true)
  private List<Input> input;
  
  public String getParam1() {
    return param1;
  }

  public void setParam1(String param1) {
    this.param1 = param1;
  }

  public List<Input> getInput() {
    return input;
  }

  public void setInput(List<Input> input) {
    this.input = input;
  }

}

 

返回是一个集合类型：

@ApiOperation(value="获取用户信息集合", notes="根据输入类型来获取用户信息集合")
    @PostMapping("/find2")
    @ApiResponse(response = User.class, responseContainer="List", code = 200, message = "请求成功")
    public List<User> find2(@ApiParam(value="传入参数类型", required=true) @RequestBody Params params) {
      
      return new ArrayList<User>();
    }

 

ui上点击对应方法，可以看到：

 

 

可以看到，现在无论是对于接口里再复杂的输入和输出，都能比较清楚地看到每个属性（字段）的含义，以及可以在swagger的ui上直接用Try it out 按钮来测试接口的可用性。

 

swagger可以很好地帮助我们管理项目接口~，以及不同业务侧之间的接口对接工作。