开发者社区> jmcui> 正文
阿里云
为了无法计算的价值
打开APP
阿里云APP内打开

SpringMVC 中配置 Swagger 插件.

简介: 一、简介  Swagger的目标是为REST API定义一个与语言无关的标准接口,允许用户发现和理解计算机服务的功能,而无需访问源代码。当通过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函数的工作方式)。默认是服务器返回的顺序不变。

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
springmvc+swagger2
一、swagger2依赖 io.springfox springfox-swagger2 spring-aop org.
1438 0
Swagger入门教程
前言 Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码,了解更多内容,见参考资料。 Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
5751 0
Spring Boot使用Swagger2自动化文档与测试
本文目录 1. 场景 2. Swagger2用了就是爽 3. 具体实现 3.1 导入依赖 3.2 添加Swagger2配置类 3.3 配置静态资源访问 3.4 启动项目并进行查看、测试 3.5 通过注解自动生成API文档 4. 总结
71 0
Apifox如何一键导入Swagger数据?
Apifox如何一键导入Swagger数据?这个问题大家知道了吧!Apifox 的整体功能比 swagger 丰富,支持一整个团队的协作,而且免费国产软件。类似swagger的工具,只能说Apifox更全面,让我找到一个合适的技术工具提高我们的效率。
61 0
spring boot 下swagger2 的使用
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。 swagger 官方Demo供参考 https://petstore.swagger.io/ swagger注解 swagger通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息的等等。 API详细说明 @Api(tags = "收付费方式变更") 常用 @ApiOperation("获取用户列表") 常用 @ApiParam(v
26 0
linux守护进程--定期向文件中插入log记录
<p>        要求:<span style="font-family:'Microsoft YaHei UI','Microsoft YaHei',SimSun,'Segoe UI',Tahoma,Helvetica,sans-serif,'Microsoft YaHei',Georgia,Helvetica,Arial,sans-serif,宋体,PMingLiU,serif;
1791 0
浅析如何在Nancy中使用Swagger生成API文档
原文:浅析如何在Nancy中使用Swagger生成API文档 前言 上一篇博客介绍了使用Nancy框架内部的方法来创建了一个简单到不能再简单的Document。但是还有许许多多的不足。 为了能稍微完善一下这个Document,这篇引用了当前流行的Swagger,以及另一个开源的Nancy.Swagger项目来完成今天的任务! 注:Swagger是已经相对成熟的了,但Nancy(2.0.0-clinteastwood)和Nancy.Swagger(2.2.6-alpha)是基于目前的最新版本,但目前的都是没有发布正式版,所以后续API可能会有些许变化。
1252 0
+关注
90
文章
0
问答
文章排行榜
最热
最新
相关电子书
更多
低代码开发师(初级)实战教程
立即下载
阿里巴巴DevOps 最佳实践手册
立即下载
冬季实战营第三期:MySQL数据库进阶实战
立即下载