当前位置:必发365电子游戏 > 编程 > Swagger 注演说明
Swagger 注演说明
2019-12-19

一、简介

 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 = "登陆客商"卡塔尔国

图片 1

三、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文件,暗中认可是从连接 获取 API 的 JSON,这里必要将url值校勘为 。其余,供给配置一下Spring MVC的财富放行:<mvc:resources mapping="/swagger/**" location="/swagger/"/>
    图片 2

tips:Swagger 注演说明。暗中认可的dist 目录下没好似此多文件,swagger-ui 能够自定义配置,这一个是大家项目中央银行使的,不用改项目名,项目名动态获取:

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

图片 3

apisSorter :对API /标签列表应用排序。它能够是'阿尔法'(按名称排序)或函数(请参阅Array.prototype.sort()以通晓sort函数的做事规律)。暗中认可是服务器重回的依次不改变。

operationsSorter :对每个API的操作列表应用四个排序。它能够是'阿尔法'(按字母数字排序),'method'(按HTTP方法排序)或函数(参见Array.prototype.sort()来明白sort函数的劳作议程)。默许是服务器再次来到的次第不改变。