swagger管理接口工程简单搭建

Posted 2021-12-28 wuaiting

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

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

1. 在pom.xml引入swagger所需依赖包：

  1 <!-- swagger2核心依赖 -->
  2 <dependency>
  3     <groupId>io.springfox</groupId>
  4     <artifactId>springfox-swagger2</artifactId>
  5 </dependency>
  6 <!-- swagger-ui为项目提供api展示及测试的界面 -->
  7 <dependency>
  8     <groupId>io.springfox</groupId>
  9     <artifactId>springfox-swagger-ui</artifactId>
 10 </dependency>
 11 

 

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

Swagger2Configuration.class

  1 import org.springframework.context.annotation.Bean;
  2 import org.springframework.context.annotation.Configuration;
  3 import springfox.documentation.builders.ApiInfoBuilder;
  4 import springfox.documentation.builders.PathSelectors;
  5 import springfox.documentation.builders.RequestHandlerSelectors;
  6 import springfox.documentation.service.ApiInfo;
  7 import springfox.documentation.spi.DocumentationType;
  8 import springfox.documentation.spring.web.plugins.Docket;
  9 import springfox.documentation.swagger2.annotations.EnableSwagger2;
 10 
 11 
 12 @Configuration
 13 @EnableSwagger2
 14 public class Swagger2Configuration 
 15     @Bean
 16     public Docket createRestApi() 
 17         return new Docket(DocumentationType.SWAGGER_2)
 18                 .apiInfo(apiInfo())
 19                 .select()
 20                 .apis(RequestHandlerSelectors.basePackage("com.xuecheng"))
 21                 .paths(PathSelectors.any())
 22                 .build();
 23     
 24 
 25     private ApiInfo apiInfo() 
 26         return new ApiInfoBuilder()
 27                 .title("文件上传下载Demo")
 28                 .description("文件上传下载Demo")
 29 //                .termsOfServiceUrl("/")
 30                 .version("1.0")
 31                 .build();
 32     
 33 
 34 

 

3. 如何使用？

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

其实通过单独建一个api接口让controller去实现它，避免大量注解内容让controller看着太乱

这里直接在Controller层（类）上这样注解

  1 @Api(value = "SWAGGER接口")
  2 @RestController
  3 @RequestMapping(value = "/api/swagger/user")
  4 public class SwaggerController
  5   @ApiOperation(value="获取用户详细信息", notes="根据参数来获取用户详细信息")
  6     @ApiImplicitParams(
  7         @ApiImplicitParam(name = "id", value = "用户ID", dataType = "Long", paramType = "query"),
  8         @ApiImplicitParam(name = "name", value = "用户名字", required = true, dataType = "String", paramType = "query"),
  9         @ApiImplicitParam(name = "age", value = "用户年龄", dataType = "Long", paramType = "query")
 10     )
 11     @RequestMapping(value="", method=RequestMethod.GET)
 12     @PostMapping("/find1")
 13     public  User find (@ModelAttribute User user) //@ModelAttribute User user 等效于Long id, String name; Long age;  
 14         return new User();
 15     
 16 

其中User类如下：

  1 //@ApiModel(value="User", description="用户对象")  
  2 public class User 
  3   @ApiModelProperty(value = "用户ID", required = true)
  4     private Long id;
  5   @ApiModelProperty(hidden = true)
  6     private String name;
  7   @ApiModelProperty(value = "用户年龄")
  8     private Long age;
  9   public void setId(Long id) 
 10     this.id = id;
 11   
 12   public void setName(String name) 
 13     this.name = name;
 14   
 15   public void setAge(Long age) 
 16     this.age = age;
 17   
 18   public Long getId() 
 19     return id;
 20   
 21   public String getName() 
 22     return name;
 23   
 24   public Long getAge() 
 25     return age;
 26   
 27 
 28 
 29 
 30 

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

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

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

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

  1 //@ApiModel(value="Params", description="传入参数")  
  2 public class Params 
  3   @ApiModelProperty(name="param1", value = "参数1", required = true)
  4   private String param1;
  5 
  6   @ApiModelProperty(name="input", value = "输入", required = true)
  7   private List<Input> input;
  8 
  9   public String getParam1() 
 10     return param1;
 11   
 12 
 13   public void setParam1(String param1) 
 14     this.param1 = param1;
 15   
 16 
 17   public List<Input> getInput() 
 18     return input;
 19   
 20 
 21   public void setInput(List<Input> input) 
 22     this.input = input;
 23   
 24 
 25 

返回是一个集合类型：

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

 

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

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