Swagger与postman使用心得

时间 2019-12-18

标签 swagger postman 使用心得繁體版

原文原文链接

Swagger接口文档，在线自动生成模板和页面。服务器地址加上swagger-ui.html后缀便可访问到（https://域名:端口号/swagger-ui.html）。

使用时在java代码中引用navan管理pom.xml中添加依赖：

  
  
  
  
   
 
    
     
      
     
     
      
      <!-- Swagger-mvc --> 
      
     
 
    
     
      
     
     
      
      <dependency> 
      
     
 
    
     
      
     
     
      
      <groupId>com.mangofactory 
      </groupId> 
      
     
 
    
     
      
     
     
      
      <artifactId>swagger-springmvc 
      </artifactId> 
      
     
 
    
     
      
     
     
      
      <version>1.0.2 
      </version> 
      
     
 
    
     
      
     
     
      
      </dependency>

我在项目中使用的是SpringBoot框架，减小了不少的配置信息

在进行接口设计的Controller中，只须要使用Swagger注解。其中下面的@Api、@ApiOperaction、@Apiparam都是Swagger注解：

其中@Api表示这是一个须要Swagger表示的类写在Controller的头部，如图；

@ApiOperaction表示这是一个须要Swagger修饰的接口，其中代表了请求方式、说明等信息。@ApiParam表示该接口输入的参数：

value是参数的值说明；name表示变量名；paramType表示传入类型，我所知类型：请求头传入写query,JSON类型传入写json；defaultValue表示默认值；required表示参数是否必须传。 API接口文档标识的内容只用于注释，没有实际意义，表示必须传入，只在文档中提示，没传不提示报错。若想判断，可在参数前些@requestParam注解

写好API注解文档后，启动项目。能够在swagger.html中对接口进行模拟测试，简单方便。

在对应字段中输入测试值，点击try it out请求接口，返会参数将在respnseBody中展现：

以上就是Swagger对接口管理和测试的简单实用方法，另外它还能够对Bean进行注释和管理。
html

对于一个实体模型，须要使用swagger去标识。以下面的Student模型，其中的@ApiModel、@ApiModelProperty都是属于Swagger的注解。若是须要在接口中返回模型对象，则须要使用如下的方式去注解。前端

  
  
  
  
   
 
    
     
      
     
     
     
       @ApiModel(value = "学生对象", description = "student") 
      
     
 
    
     
      
     
     
     
       public class Student { 
      
     
 
    
     
      
     
     
      
      
     
 
    
     
      
     
     
     
       @ApiModelProperty(value = "姓名", required = true) 
      
     
 
    
     
      
     
     
     
       String name; 
      
     
 
    
     
      
     
     
     
       @ApiModelProperty(value = "年龄", required = true) 
      
     
 
    
     
      
     
     
     
       String age; 
      
     
 
    
     
      
     
     
      
      
     
 
    
     
      
     
     
     
       public Student(String name, String age) { 
      
     
 
    
     
      
     
     
     
       this.name = name; 
      
     
 
    
     
      
     
     
     
       this.age = age; 
      
     
 
    
     
      
     
     
     
       } 
      
     
 
    
     
      
     
     
      
      
     
 
    
     
      
     
     
     
       public String getName() { 
      
     
 
    
     
      
     
     
     
       return name; 
      
     
 
    
     
      
     
     
     
       } 
      
     
 
    
     
      
     
     
      
      
     
 
    
     
      
     
     
     
       public void setName(String name) { 
      
     
 
    
     
      
     
     
     
       this.name = name; 
      
     
 
    
     
      
     
     
     
       } 
      
     
 
    
     
      
     
     
      
      
     
 
    
     
      
     
     
     
       public String getAge() { 
      
     
 
    
     
      
     
     
     
       return age; 
      
     
 
    
     
      
     
     
     
       } 
      
     
 
    
     
      
     
     
      
      
     
 
    
     
      
     
     
     
       public void setAge(String age) { 
      
     
 
    
     
      
     
     
     
       this.age = age; 
      
     
 
    
     
      
     
     
     
       } 
      
     
 
    
     
      
     
     
     
       }

我目前更多的使用Swagger管理API文档，测试接口。管理Bean我的并不经常使用。能够把Swagger理解为接口文档，后台写好的代码能够直接生成前端接口文档页面，接口调用这能够经过这个页面发送接口请求，进行接口测试或调用。对接方便。无奈的是，返回参数的接口文档，仍是要本身写啊。

Postman插件，postman只是Chrome浏览器一个控件，能够嵌在Chrome中使用，也能够单独下载软件版。用来测试接口很是只方便。并且能够分类管理测试过的接口。分享接口
java

它得好处就是能够记忆测试的参数，Swagger毕竟是网页打开，不少参数没法保存。对家数据测试形成不小困扰，另外。设计到token权限的话，swagger中可能每次都须要模拟登陆，而postman在Header中保存Token信息。给测试带来便利，按照程序员的尿性，我推荐postman。清晰整齐，一目了然。

那么他如何与前端对接呢，写接口文档吗？能够，或者你可以让你家前端本身也下载一个，你把你测试的接口整理给他。就看他愿不肯意用咯。
程序员

总结：后台测试，推荐使用Postman。可是最好养成写Swagger的习惯，第一是能够给前端看，让他们参考。更重要的是postman中的测试可能会丢失。可是写在代码里的Swagger永远不会丢。
spring