SpringMVC 中配置 Swagger 插件.

一、简介

 Swagger的目标是为REST API定义一个与语言无关的标准接口,允许用户发现和理解计算机服务的功能,而无需访问源代码。当通过Swagger正确定义时,用户可以用最少量的实现逻辑理解远程服务并与之交互。类似于低级编程所做的接口。

二、实现步骤

1、添加 Maven 依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

2、Swagger 配置类

@Configuration
@EnableSwagger2
//@ComponentScan(basePackageClasses = JgBjBaseInfoCompanyApi.class) 或者
@ComponentScan(basePackages = "com.summersoft.ts.schedule.supervision.controller") //要扫描的包路径
public class SwaggerConfig {

    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select() //选择哪些路径和api会生成document
                .apis(RequestHandlerSelectors.any())//对所有Api进行监控
                .paths(PathSelectors.any()) //对所有路径进行扫描
                .build();
    }

    /**
     * api具体信息
     *
     * @return
     */
    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
                "对接服务平台API文档", //标题
                "", //描述
                "1.0", //版本
                "",
                "",
                "", //签名
                "" //签名链接
        );
        return apiInfo;
    }
}

3、Swagger 注解 

Swagger 会去扫描SwaggerConfig 中配置的包路径下的带有Swagger 注解的类文件,并最后生成一串扫描的Json文件...

Swagger 注解说明:https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

@Api :用在类上,说明该类的作用,需要说明的是较老的版本用的value表示扫描生成的类名,1.5后要用tag 表示类名 @Api(tag= "UserController", description = "用户相关api") @ApiOperation :用在方法上,说明方法的作用  @ApiOperation(value = "查找用户", notes = "查找用户", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

@ApiParam  :用在参数列表中,表明参数的含义

        @ApiParam(value = "创建或更新距离当前时间(月)") Integer time

@ApiImplicitParams :用在方法上包含一组参数说明 @ApiImplicitParam :用在@ApiImplicitParams注解中,指定一个请求参数的各个方面    paramType:参数放在哪个地方    header–>请求参数的获取:@RequestHeader    query–>请求参数的获取:@RequestParam    path(用于restful接口)–>请求参数的获取:@PathVariable    body(不常用)    form(不常用)    name:参数名    dataType:参数类型    required:参数是否必须传    value:参数的意思    defaultValue:参数的默认值        @ApiImplicitParams({        @ApiImplicitParam(name = "id", value = "唯一id", required = true, dataType = "Long", paramType = "path"),        })

@ApiResponses :用于表示一组响应 @ApiResponse :用在@ApiResponses中,一般用于表达一个错误的响应信息   code:数字,例如400   message:信息,例如”请求参数没填好”   response:抛出异常的类      @ApiResponses(value = {      @ApiResponse(code = 400, message = "No Name Provided")      })

@ApiModel :描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候) @ApiModel(value = "用户实体类") @ApiModelProperty :描述一个model的属性 @ApiModelProperty(value = "登录用户")

三、swagger-ui 

    有了上面的配置信息,Swagger 就会帮我们扫描出所有的 类信息,并生成一个JSON文件。想让JSON文件友好的展示在人们面前,需要用到 swagger-ui 这个组件:  

    1、 swagger-ui 使用说明https://swagger.io/docs/swagger-tools/

 2、下载 swagger-ui  ,在webapp 目录下新建一个swagger目录,把 dist 目录下的文件,放入swagger目录下,并修改index.html文件,默认是从连接 http://petstore.swagger.io/v2/swagger.json 获取 API 的 JSON,这里需要将url值修改为 http://{ip}:{port}/{projectName}/api-docs的形式,{}中的值根据自身情况填写。比如我的url值为:http://localhost:8080/vouchers/api-docs 。另外,需要配置一下Spring MVC的资源放行:<mvc:resources mapping="/swagger/**" location="/swagger/"/>

tips:默认的dist 目录下没有这么多文件,swagger-ui 可以自定义配置,这个是我们项目中使用的,不用改项目名,项目名动态获取:https://files.cnblogs.com/files/jmcui/swagger.zip

3、swagger-ui 怎么对展示的接口排序:

apisSorter :对API /标签列表应用排序。它可以是'alpha'(按名称排序)或函数(请参阅Array.prototype.sort()以了解sort函数的工作原理)。默认是服务器返回的顺序不变。

operationsSorter :对每个API的操作列表应用一个排序。它可以是'alpha'(按字母数字排序),'method'(按HTTP方法排序)或函数(参见Array.prototype.sort()来知道sort函数的工作方式)。默认是服务器返回的顺序不变。

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏SpiritLing

Appserv(Apache) 配置ssl证书

一:打开httpd.conf文件,移除注释的行: Include conf/extra/httpd-ahssl.conf LoadModule ssl_modu...

89160
来自专栏编程坑太多

springboot (九) Swagger2实现Restful API

22220
来自专栏battcn

一起来学SpringBoot | 第十一篇:集成Swagger在线调试

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、前后端分离的形态,而且前端和后端在各自的技术道路上越走越远。

11230
来自专栏xingoo, 一个梦想做发明家的程序员

Apache虚拟主机-解惑篇

    有很多平时喜欢钻研的童鞋会发现,为什么有时候自己访问某XXse网站时,总是更新IP地址,内容却与以前一样。这个时候就要了解虚拟主机的概念了。了解这个概...

31950
来自专栏专注于主流技术和业务

REST API文档工具Swagger2,以及与SpringBoot的集成

swagger是一个API框架,号称世界上最流行的API工具。它提供了API管理的全套解决方案,比如API在线编辑器,APIUI展示界面,代码生成器等诸多功能。...

11720
来自专栏乐沙弥的世界

Apache httpd 2.4 访问控制

Apache访问控制可以由几个不同的模块完成。其中最重要的是mod_authz_core和mod_authz_host。Apache使用Require指令进行授...

18320
来自专栏xingoo, 一个梦想做发明家的程序员

Elasticsearch+Logstash+Kibana教程

参考资料 累了就听会歌吧! Elasticsearch中文参考文档 Elasticsearch官方文档 Elasticsearch 其他——那些年遇到的坑 El...

50370
来自专栏dalaoyang

SpringBoot使用Swagger2实现Restful API

很多时候,我们需要创建一个接口项目用来数据调转,其中不包含任何业务逻辑,比如我们公司。这时我们就需要实现一个具有Restful API的接口项目。 本文介绍sp...

44280
来自专栏小尘哥的专栏

美化一下你的API文档吧(springboot集成swagger及遇到的问题)

微服务的流行提供了诸多的方便,随着也带来了N多的API,而swagger2正是一个对API管理的很好的“工具”,本文主要介绍springboot对swagger...

25430
来自专栏Albert陈凯

2018-11-18 swagger2 自动生成API

作者:小莫 链接:https://www.zhihu.com/question/28119576/answer/134580038 来源:知乎 著作权归作...

31430

扫码关注云+社区

领取腾讯云代金券