SpringMVC 中配置 Swagger 插件.

一、简介

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

二、实现步骤

1、添加 Maven 依赖

<dependency>
    groupId>io.springfox</artifactId>springfox-swagger2version>2.6.1>
>

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 =  ApiInfo(
                "对接服务平台API文档",标题
                "",1)">描述
                "1.0",1)">版本
                "",""签名
                "" 签名链接
        );
        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函数的工作方式）。默认是服务器返回的顺序不变。

四、Spring Boot 集成

依赖于 Spring Boot 中的 starter 和?autoconfig 组件。在 Boot 中使用 Swagger 是再轻松不过的事情了。

        >
            >2.9.2>
        >

        >springfox-swagger-ui>

然后再配置上面提到的?SwaggerConfig.java（也能在 application.yml 中配置，个人更喜欢配置类的方式）?这样就集成好了 swagger 组件和 swagger-ui 。怎么样？简单吧！

（编辑：北几岛）

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!