SpringBoot指南|第四篇:集成swagger生成API文档

SpringBoot指南|第四篇:集成swagger生成API文档

本文介绍如何使用swagger生成API文档。


为什么需要API的文档

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、前后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架。


目录

  • 1.依赖jar包
  • 2.swagger 的自动注入配置
  • 3.swagger-ui API文档生成使用
  • 4.结语

使用指南

1.依赖jar包

<!-- API Swagger begin -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.5.0</version>
  <scope>compile</scope>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.5.0</version>
  <scope>compile</scope>
</dependency>
<dependency>
  <groupId>net.minidev</groupId>
  <artifactId>json-smart</artifactId>
  <version>2.3</version>
</dependency>
<dependency>
  <groupId>org.json</groupId>
  <artifactId>json</artifactId>
  <version>20171018</version>
</dependency>
<!-- API Swagger end -->

2.swagger 的自动注入配置

源码

/**
 * com.xxx.web.config.SwaggerConfig.java
 * Copyright 2018 Lifangyu, Inc. All rights reserved.
 */
package com.xxx.configs;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Conditional;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Desc:swagger api 的配置
 * <p>
 * 访问:http://ip:port/swagger-ui.html
 * [localhsot:8081/swagger-ui.html 可能有登录拦截,需要先登录系统后在访问该地址]
 * </p>
 * <p>
 * Created by lifangyu on 2018/3/19.
 */
@Conditional(SwaggerCondition.class)
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * /api.* [访问的路径匹配,如:SwaggerApiController.java @RequestMapping("/api/v1") 符合该路径匹配]
     *
     * @return
     */
    @Bean
    public Docket userApi() {

        // 添加多个header或参数
        /*ParameterBuilder parameterBuilder1 = new ParameterBuilder();
        parameterBuilder1.name("clientCode").description("访问的系统clientCode").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        ParameterBuilder parameterBuilder2 = new ParameterBuilder();
        parameterBuilder2.name("timestamp").description("请求api的当前时间(long[yyyy-MM-dd HH:hh:ss SSS])").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        ParameterBuilder parameterBuilder3 = new ParameterBuilder();
        parameterBuilder3.name("encrypt-key").description("请求api的认证密文").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        List<Parameter> parameterList = new ArrayList<Parameter>();
        parameterList.add(parameterBuilder1.build());
        parameterList.add(parameterBuilder2.build());
        parameterList.add(parameterBuilder3.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(false).globalOperationParameters(parameterList)
                .select()
                .paths(PathSelectors.regex("/api.*"))
                .build();*/

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()// 选择那些路径和api会生成document
                .apis(RequestHandlerSelectors.any()) // 对所有@Api注解进行监控
//                .paths(PathSelectors.any()) // 对所有路径进行监控[指定匹配路径监控(PathSelectors.regex("/api.*"))]
                .build();
    }

    /**
     * 确保以下配置的信息可用,否则不能访问
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("****-**系统接口文档")
                .description("**-server系统接口文档")
                .license("Apache license")
                .version("2.0")
                .build();
    }
}

为了防止在生产环境恶意攻击api接口,建议关闭生产环境通过swagger api对接口的访问,源码:

/**
 * com.xxx.web.config.SwaggerCondition.java
 * Copyright 2018 Lifangyu, Inc. All rights reserved.
 */
package com.xxx.configs;

import org.springframework.context.annotation.Condition;
import org.springframework.context.annotation.ConditionContext;
import org.springframework.core.type.AnnotatedTypeMetadata;

/**
 * Desc:指定swagger api 生成的条件:非生产环境生成
 * <p>
 * Created by lifangyu on 2018/3/19.
 */
public class SwaggerCondition implements Condition {

    @Override
    public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
        return !"prod".equals(context.getEnvironment().getProperty("spring.profiles.active"));
    }

}

3.swagger-ui API文档生成使用

3.1:在写好的 api controller 上添加注解 @Api(value = "demo controller", protocols = "json")

说明:指定该controller使用swagger生成api文档;

3.2:在方法上添加注解
@ApiOperation(value = "系统-方法", httpMethod = "POST", notes = "接口简介")

说明:该方法使用swagger 生成api接口文档,提供测试服务;

demo


@RestController
@Slf4j
@Api
@RequestMapping("/xxx/api/v1")
public class GpsApi {
 ...
 
    @PostMapping("syncGpsInfo")
    @ApiOperation(value = "测试系统-gps信息同步", httpMethod = "POST", notes = "gps信息同步")
    @RequestLogger("测试系统-gps信息同步[/as/api/v1/syncGpsInfo]")
    @ResponseBody
    public ResponseVo syncGspInfo(@RequestBody RequestVo<GpsSyncRequestVo> requestVo) {

     ......
     
    }
 
 ...
 
 
}

swagger-ui api文档 的访问

启动应用,在浏览器输入:http://ip:port/swagger-ui.html

类似下图:


swagger.png

可以提供接口api文档的说明和api的测试!

附:swagger 生成API文档的注释


@Api:用在类上,说明该类的作用。

@ApiOperation:注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam:用来注解来给方法入参增加说明。

@ApiResponses:用于表示一组响应

@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息

    1.code:数字,例如400

    2.message:信息,例如"请求参数没填好"

    3.response:抛出异常的类   

@ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)

@ApiModelProperty:描述一个model的属性

注意:@ApiImplicitParam的参数说明:
    1.paramType:指定参数放在哪个地方
    2.header:请求参数放置于Request Header,使用@RequestHeader获取
    3.query:请求参数放置于请求地址,使用@RequestParam获取
    4.path:(用于restful接口)-->请求参数的获取:@PathVariable
    5.body:(不常用)
    6.form(不常用)
    7.name:参数名 
    8.dataType:参数类型
    9.required:参数是否必须传 true | false
    10.value:说明参数的意思 
    11.defaultValue:参数的默认值

结语

到此本文就结束了,关注公众号查看更多推送!!!


关注我的公众号

推荐阅读更多精彩内容