swagger的基本概念和基本配置

swagger的基本概念和基本配置

是什么
是一个简单的Restful API文档生成管理工具，根据我们自己的配置信息能够自动生成丶描述丶调用和可视化restful风格并且实时更新的web服务，可以让人和计算机拥有无须访问源码丶文档或网络流量监测就可以发现和理解服务的能力。其官方网站为：http://swagger.io/
有什么用(为什么要用,目的)
把相关信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。swagger，可以通过扫描代码去生成这个描述文件，连描述文件都不需要去维护了，所有的代码和信息都在里面。代码即接口文档，接口文档及代码。
接口的文档在线自动生成
在哪里用(什么情况下用)
swagger注解使用场景
@ApilmplicitParams：用在方法上包含一组参数说明
@ApilmplicitParam：用在@ApilmplicitParams注解中，指定一个请求参数的各个方面
怎么用
使用第三方依赖，直接在pomxml文件中添加第三方的swagger依赖，在springboot项目的启动类中添加@enableSwagger2Doc注解。
优缺点
优：支持API自动生成同步的在线文档，使用swagger后可以直接通过代码生成文档，不再需要自己手动编写文档，可以节约写文档的时间。
提供web页面在线测试API：参数和格式都是定好了的，直接在界面上输入参数对应的值即可在线测试接口。
springboot集成Swagger：
1丶pom包配置

io.springfox
springfox-swagger2
2.9.2

io.springfox springfox-swagger-ui 2.9.2 2丶添加Swagger配置文件 @Configuration @EnableSwagger2 public class SwaggerConfig{ /** * 创建一个Docket对象 * 调用select()方法， * 生成ApiSelectorBuilder对象实例，该对象负责定义外漏的API入口 * 通过使用RequestHandlerSelectors和PathSelectors来提供Predicate，在此我们使用any()方法，将所有API都通过Swagger进行文档管理 * @return */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); }

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            //标题
            .title("Spring Boot中使用Swagger2构建RESTful APIs")
            //简介
            .description("")
            //服务条款
            .termsOfServiceUrl("")
            //作者个人信息
            .contact(new Contact("chenguoyu","","[email protected]"))
            //版本
            .version("1.0")
            .build();
}

}

3丶配置静态访问资源
@Configuration
启动项目
public class WebMvcConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
// 解决 swagger-ui.html 404报错
registry.addResourceHandler("/swagger-ui.html").addResourceLocations(“classpath:/META-INF/resources/”);
}
访问接口
http://localhost:8080/swagger-ui.html

注：参考文献baidu.com