swagger
swagger
swagger是什么?
是一个可以自动生成接口文档和客户端代码,保证调用端代码,服务端代码以及接口文档一致性的工具。
–别人详细的解释:
发现了痛点就要去找解决方案。解决方案用的人多了,就成了标准的规范,这就是Swagger的由来。通过这套规范,你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。这样,如果按照新的开发模式,在开发新版本或者迭代版本的时候,只需要更新Swagger描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。
但即便如此,对于许多开发来说,编写这个yml或json格式的描述文件,本身也是有一定负担的工作,特别是在后面持续迭代开发的时候,往往会忽略更新这个描述文件,直接更改代码。久而久之,这个描述文件也和实际项目渐行渐远,基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring,迅速将Swagger规范纳入自身的标准,建立了Spring-swagger项目,后面改成了现在的Springfox。通过在项目中引入Springfox,可以扫描相关的代码,生成该描述文件,进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式,在后面需求持续迭代的项目中,显得尤为重要和高效。
作者:wuqke
链接:https://www.jianshu.com/p/349e130e40d5
来源:简书
著作权归作者所有。商业转载请联系作者获得授权,非商业转载请注明出处。
swagger入门使用
1导入依赖
<dependency>
<groupId>net.bookrain</groupId>
<artifactId>swagger2</artifactId>
<version>0.0.1</version>
</dependency>
2 开启swagger 功能
@EnableSwagger2
注册swagger2 bean
package com.wang.config;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Controller;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Controller
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket(){
Docket docket = new Docket(DocumentationType.SWAGGER_2);
return docket;
}
}
3 使用
经过前面两步,swagger就集成到我们的spring boot项目里面了。下面就来查看一下:
http://localhost:8088/swagger-ui.html
可以看到,swagger对我们的controller,model都全局监控起来了。
4 swagger使用
使用Docket 来实现定制功能。
例如:apiInfo().enable() 实现环境切换
package com.wang.config;
import com.google.common.base.Strings;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Profile;
import org.springframework.core.env.Environment;
import org.springframework.stereotype.Controller;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.Arrays;
@Controller
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket(Environment environment){
final Contact DEFAULT_CONTACT = new Contact("ZhiPanWang", "", "zhi@qq.com");
// 定义页面的一些信息
ApiInfo apiInfo = new ApiInfo("Api Documentation", "Api Documentation", "v1.0", "urn:tos",DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
String[] actives = environment.getActiveProfiles();
boolean flag=false;
if (Arrays.binarySearch(actives,"dev")>-1) {
flag = true;
}
// eable() 可以根据环境决定是否开启swagger,例如配置了dev 和pro .现在使用pro .那么flag就为false
Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo).enable(flag);
return docket;
}
}