服务器之家

服务器之家 > 正文

SpringMVC 中配置 Swagger 插件的教程(分享)

时间:2021-03-11 13:34     来源/作者:JMCui

一、简介

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

二、实现步骤

1、添加 maven 依赖

?
1
2
3
4
5
<dependency>
 <groupid>io.springfox</groupid>
 <artifactid>springfox-swagger2</artifactid>
 <version>2.6.1</version>
</dependency>

2、swagger 配置

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
@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 = "登录用户")

SpringMVC 中配置 Swagger 插件的教程(分享)

三、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/"/>

SpringMVC 中配置 Swagger 插件的教程(分享)

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

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

SpringMVC 中配置 Swagger 插件的教程(分享)

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

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

以上这篇springmvc 中配置 swagger 插件的教程(分享)就是小编分享给大家的全部内容了,希望能给大家一个参考,也希望大家多多支持服务器之家。

原文链接:http://www.cnblogs.com/jmcui/archive/2017/12/24/8098268.html

标签:

相关文章

热门资讯

2020微信伤感网名听哭了 让对方看到心疼的伤感网名大全
2020微信伤感网名听哭了 让对方看到心疼的伤感网名大全 2019-12-26
yue是什么意思 网络流行语yue了是什么梗
yue是什么意思 网络流行语yue了是什么梗 2020-10-11
背刺什么意思 网络词语背刺是什么梗
背刺什么意思 网络词语背刺是什么梗 2020-05-22
Intellij idea2020永久破解,亲测可用!!!
Intellij idea2020永久破解,亲测可用!!! 2020-07-29
苹果12mini价格表官网报价 iPhone12mini全版本价格汇总
苹果12mini价格表官网报价 iPhone12mini全版本价格汇总 2020-11-13
返回顶部