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

一、简介

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 = "登录用户")

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 插件的教程(分享)