swagger simple management interface engineering structures

Description : Swagger Rest is a simple yet powerful API representation standard, language-independent, this representation is not only a human-readable and machine-readable. Rest API can be used as an interactive document can also be described as an interface formalization Rest API to generate client and server code.

Below in conjunction with the more common scenario, probably referring to the next how to use the swagger in Springboot to manage the interface for front and back end developers to do a good docking interface, but also conducive to the development of follow-up maintenance interface.

1. pom.xml dependencies introduced swagger required:

  . 1  <-! Swagger2 Core dependent -> 
  2  < dependency > 
  . 3      < the groupId > io.springfox </ the groupId > 
  . 4      < the artifactId > springfox-swagger2 </ the artifactId > 
  . 5  </ dependency > 
  . 6  <-! Swagger-UI api provides display and interface test project -> 
  . 7  < dependency > 
  . 8      < the groupId > io.springfox </ the groupId > 
  . 9      < the artifactId >springfox-swagger-ui</artifactId>
 10 </dependency>
 11 

 

2. Specify the swagger of some static resource configuration file, usually with a class to manage and maintain

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 is      }
 24  
25      Private ApiInfo apiInfo () {
 26 is          return  new new ApiInfoBuilder ()
 27                  .title ( " file upload and download Demo ")
 28                  .description ( " file upload and download Demo ")
 29  // .termsOfServiceUrl ( " / ") 
30                  .version (" 1.0 ")
 31 is                  .build ();
 32      }
 33 is  
34 is }

 

3. How to use?

This step I will use the more common business scenarios to describe the interface:

In fact, to achieve it by building a separate api interface to allow controller, to avoid a large number of annotated content allows controller looked too messy

Such annotations directly on this layer Controller (s)

  . 1 @Api (value = " SWAGGER Interface ")
   2 @RestController
   . 3 @RequestMapping (value = " / API / Swagger / User ")
   . 4  public  class SwaggerController {
   . 5    @ApiOperation (value = " get user details ", notes = " Details to obtain the user according to the parameter ")
   . 6      @ApiImplicitParams ({
   . 7          @ApiImplicitParam (name =" ID ", value =" user 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 }

Wherein the User class is as follows:

  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 class is an entity corresponding to ~ query or the query results, each of which need @ApiModelProperty attribute to describe the meaning of each field; @ApiModel annotations on User classes can be given selectively.

Access swagger interface description page simply start the project (here springboot), then type http: // localhost: 8080 / swagger-ui.html # to access, we click on the corresponding Controller and interfaces, you can see!:

Paramters region is described input parameter, and is described output Response, Response may switch to a Model, you can see the field of the output means:

2) request parameters are complex, this time must correspond to an entity class, such as:

  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可以很好地帮助我们管理项目接口~，以及不同业务侧之间的接口对接工作。