Swagger-强大的API文档工具

猫公子xiu 2019-06-16

2057

为什么需要swagger ？

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。

swagger 简介

Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。

官网地址：https://swagger.io/

具有准确性的API模型

API设计容易出错，在建模API时发现和纠正错误是非常困难和耗时的。Swagger Editor是第一个使用OpenAPI规范（OAS）设计API的编辑器，并且继续满足开发人员使用OAS构建API的需求。编辑器实时验证您的设计，检查OAS合规性，并随时提供视觉反馈。

在设计时可视化

最好的API是针对最终消费者而设计的。像Swagger编辑器和SwaggerHub这样的Swagger工具为YAML编辑器提供了一个可视化面板，供开发人员使用，并查看API对最终消费者的外观和行为。

在整个团队中标准化您的设计风格

提供共享通用行为，模式和一致的RESTful接口的API将极大地简化构建它们的人员和想要使用它们的消费者的工作。SwaggerHub配备了内置的API标准化工具，可以使您的API符合您的组织设计指南。

既然swagger有这么多优点，那么我们应该如何使用swagger呢？

首先在maven中引入swagger依赖：

  <!-- 用于JSON API文档的生成-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    
    <!--用于文档界面展示-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.5.21</version>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.5.21</version>
    </dependency>

添加完依赖以后创建swagger的配置类

@Configuration
@EnableSwagger2
@ConditionalOnExpression("${swagger.enable:true}")
public class SwaggerConfig {


    @Bean
    public Docket createDocket(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder().title("接口API")
                        .description("相关接口API文档")
                        .version("1.1").build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.package"))//需要扫描controller的包路径
                .paths(PathSelectors.any())
                .build();
        return docket;
    }


}

那么配置完后该如何使用呢？

启动项目访问路径：http://localhost:8080/swagger-ui.html#/

当然swagger提供了很多注解，让你更加简便

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"


@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"


@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值


@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类


@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

一般我们项目中会添加拦截器拦截，那么如何保证测试的时候既有拦截又不影响swagger呢？

下面我们在配置拦截器的时候多加一个过滤swagger的代码

@Override
  public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(new ApiInterceptor())
        .addPathPatterns("/**")
        .excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**")
        .excludePathPatterns("/user/login");
    super.addInterceptors(registry);
  }
  
  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

可以参考这篇博客：

https://blog.csdn.net/weixin_42118284/article/details/89880530

数据库

文章转载自猫公子xiu，如果涉嫌侵权，请发送邮件至：contact@modb.pro进行举报，并提供相关证据，一经查实，墨天轮将立刻删除相关内容。

Swagger-强大的API文档工具

评论