Understanding of the most popular Api framework --swagger
swagger Profile
swagger is support for multiple programming languages Api framework . It can be run directly, online testing API interface . There RestFul Api-line automatic document generation tool , and can be reached Api documentation and API definitions updated simultaneously .
Due to the wide front and rear separate development, many people can not do the front handle synchronization issues, in order to improve the processing efficiency and to avoid conflicts at work before and after the end of the staff, we need to 'immediate consultation, target sync'. For this problem, the first solution is to use: Specifies the schema and real-time updates on the latest API, word planning documents, providing back-end interfaces, front-end interface to back-end test with a postman three ways. But these methods can not achieve immediate results, so it should be a timely swagger.
As the world's most popular API framework , you need springfox (swagger when used in the project swagger2-ui and swagger ). This requires import dependence in the following two projects:
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
Integrated swagger with SpringBoot
New SpringBoot Web Project
Import swagger2 and swagger-ui -dependent
Hello to write a project for testing
Configuring swagger, write config
@Configuration @EnableSwagger2 //开启Swagger2 public class SwaggerConfig { }Run the test: http: // localhost: 8080 / swagger-ui.html
Configuration information swagger
bean instance swagger of the docket:
@Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2); }Swagger of configuration information:
//配置Swagger信息=apiInfo private ApiInfo apiInfo(){ //作者信息 Contact contact = new Contact("啊侠", "https://blog.csdn.net/weixin_44821160", "[email protected]"); return new ApiInfo( "啊侠的SwaggerAPI测试文档", "不要因为任何事情忘记自己最初的动力", "v1.0", "https://blog.csdn.net/weixin_44821160", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList() ); }
swagger scan interface configuration
Docket.select()
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//RequestHandlerSelectors，配置要扫描接口的方式
//basePackage:指定要扫描的包
//any():扫描全部
//none():不扫描
//withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
//withMethodAnnotation：扫描方法上的注解
.apis(RequestHandlerSelectors.basePackage("com.david.swagger.controller"))
//paths()。过滤什么路径
.paths(PathSelectors.ant("/david/**"))
.build();
}Configure whether to start Swagger
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(false)//enable是否启动Swagger，如果为False，则Swagger不能再浏览器中访问
.select()
.apis(RequestHandlerSelectors.basePackage("com.david.swagger.controller"))
.build();
}If you only want to use my Swagger in a production environment, do not use at the time of release will need:
- Analyzing the production environment is not flag = false
- Injection enable (flag)
//配置了Swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment){
//设置要显示的Swagger环境
Profiles profiles = Profiles.of("dev","test");
//通过environment.acceptsProfiles判断是否处在自己设定的环境当中
boolean flag = environment.acceptsProfiles(profiles);
System.out.println(flag);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(flag)
.select()
.apis(RequestHandlerSelectors.basePackage("com.david.swagger.controller"))
.build();
}Api configuration packet of documents
.groupName（“david”）
A plurality of groups, a plurality of instances docket
@Bean public Docket docket1(){ return new Docket(DocumentationType.SWAGGER_2).groupName("豪侠"); } @Bean public Docket docket2(){ return new Docket(DocumentationType.SWAGGER_2).groupName("真真"); } @Bean public Docket docket3(){ return new Docket(DocumentationType.SWAGGER_2).groupName("超强"); }Configure the entity class
package com.david.swagger.pojo; import io.swagger.annotations.Api; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; //@Api(注释) @ApiModel("用户实体类") public class User { @ApiModelProperty("用户名") public String username; @ApiModelProperty("密码") public String password; }Write controller
package com.david.swagger.controller; import com.david.swagger.pojo.User; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController public class HelloController { @GetMapping(value = "/hello") public String hello(){ return "hello"; } //只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中 @PostMapping(value = "/user") public User user(){ return new User(); } //Operation接口,不是放在类上的，是方法 @ApiOperation("Hello控制类") @GetMapping(value = "/hello2") public String hello2(@ApiParam("用户名") String username){ return "hello"+username; } @ApiOperation("Post测试类") @PostMapping(value = "/posttest") public User posttest(@ApiParam("用户名") User user){ int i = 5/0;//；模拟代码错误 return user; } }
Summarize the role of swagger
By Swagger can give some of the more difficult to understand or interface properties, add notes information. Documentation can achieve real-time updates, online testing also easy to understand api. While swagger is an excellent tool, but for security reasons close swagger before the official release, saving memory to run.