Spring-Boot + Swagger2 自动生成API接口文档

简介: spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口。这些接口不但会服务于传统的web端(b/s),也会服务于移动端。

spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口。这些接口不但会服务于传统的web端(b/s),也会服务于移动端。在实际开发过程中,这些接口还要提供给开发测试进行相关的白盒测试,那么势必存在如何在多人协作中共享和及时更新API开发接口文档的问题。
假如你已经对传统的wiki文档共享方式所带来的弊端深恶痛绝,那么尝试一下Swagger2 方式,一定会让你有不一样的开发体验:

  • 功能丰富 :支持多种注解,自动生成接口文档界面,支持在界面测试API接口功能;
  • 及时更新 :开发过程中花一点写注释的时间,就可以及时的更新API文档,省心省力;
  • 整合简单 :通过添加pom依赖和简单配置,内嵌于应用中就可同时发布API接口文档界面,不需要部署独立服务。

1、添加pom依赖

需要添加的依赖为swagger2核心包和swagger-ui界面包,笔者写文章时的最新版本为2.7.0,实际引用可以去maven官网查询最新可使用版本。

代码块

<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.7.0</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.7.0</version>
</dependency>

2、将swagger-ui中的界面配置至spring-boot环境

spring-boot有自己的一套web端拦截机制,若需要看到swagger发布的api文档界面,需要做一些特殊的配置,将springfox-swagger-ui包中的ui界面暴露给spring-boot资源环境。

代码块

@Configuration
public class WebMvcConfig extends WebMvcConfigurerAdapter {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/js/**").addResourceLocations("classpath:/js/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

3、配置API文档页基本信息

spring-boot 和 swagger 整合时,可以通过注解注入相关配置。通过这些配置可以指定在spring-boot启动时扫描哪些controller层的文件夹,另外可以指定API文档页的标题和描述信息等内容。

代码块

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xx.web.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xx项目 RESTful APIs")
                .description("xx项目后台api接口文档")
                .version("1.0")
                .build();
    }

}

4、API文档编写示例

我们一般在Controller层,将详尽的API接口输入输出在代码中通过注解进行相关描述,下面给出一个接口描写示例,具体的写法可以参考其api文档的具体说明:

代码块

@Api(value = "PageController", description = "用户登录登出接口")
@Controller
@RequestMapping("/")
public class PageController {

    @ApiOperation(value="用户登录", notes="用户登录接口")
    @ApiImplicitParams({
          @ApiImplicitParam(name = "username", value = "用户名", required = true ,dataType = "string"),
          @ApiImplicitParam(name = "passwd", value = "密码", required = true ,dataType = "string")
    })
    @RequestMapping(value = "/login",method = {RequestMethod.POST,RequestMethod.GET})
    @ResponseBody
    public ModelMap login(Users data, HttpServletRequest request){
       xxx...
    }

}

5、在线查看及测试API文档

完成API文档的编写工作之后,正常启动spring-boot,假如后台端口为8080,那么访问http://127.0.0.1:8080/swagger-ui.html,可以访问到如下界面:

img_737493d5abd065e80b0130bf0d7803b6.jpe

通过该界面,不仅可以看到自动生成的所有API文档信息,还可以对任意接口进行在线测试,非常方便:


img_2cfaa93b63671818d3bfcd781b59df6e.jpe
目录
相关文章
|
16天前
|
数据可视化 API 开发者
通俗易懂:一步步教你 Flask 项目自动生成 API 文档
Flasgger,作为一款强大的 Flask 扩展,自动从 Flask 应用中提取并生成 OpenAPI 规范文档,配备 SwaggerUI,为开发者提供了一条快捷通道,让 API 的文档编制和交互式测试变得简单易行。Flasgger 的设计原则是简化开发流程,通过与 Flask 框架的无缝整合,让开发者可以更专注于应用逻辑的构建。
|
25天前
|
前端开发 应用服务中间件 nginx
使用swagger和knife4j生成的接口文档在浏览器中输入地址后报404错误
使用swagger和knife4j生成的接口文档在浏览器中输入地址后报404错误
15 0
|
3月前
|
API 数据安全/隐私保护 网络架构
接口文档编写规范(前后端分离项目接口api)
接口文档编写规范(前后端分离项目接口api)
123 0
|
4月前
|
JavaScript API
工具 | 自动生成api接口
这是一个将swagger接口文档自动生成TypeScript的api接口以及interface定义。
|
5月前
|
运维 前端开发 JavaScript
Swagger生成接口文档
Swagger生成接口文档
77 0
|
6月前
|
前端开发 数据可视化 Java
Swagger 接口文档 | knife4j 增强方案
Swagger 接口文档 | knife4j 增强方案
105 0
Swagger 接口文档 | knife4j 增强方案
|
6月前
|
XML 数据采集 JSON
Shopee|Lazada|ebay|aliexpress|kaola东南亚电商平台API接口文档示例
Shopee|Lazada|ebay|aliexpress|kaola东南亚电商平台API接口文档示例,包括:关键词搜索商品列表接口,根据商品ID获取商品详情数据,根据 店铺ID获取店铺所有商品数据,根据商品ID获取商品评论数据,根据商品ID获取跨境属性数据。
20 0
|
6月前
|
JSON Java API
SpringBoot集成Swagger2自动生成API接口文档
SpringBoot集成Swagger2自动生成API接口文档
79 0
|
7月前
|
JSON API 数据安全/隐私保护
【Django学习】(十五)API接口文档平台_项目流程分析_日志器_认证_授权
【Django学习】(十五)API接口文档平台_项目流程分析_日志器_认证_授权
|
7月前
|
安全 数据可视化 Java
Swagger 自动生成 Api 文档:简化接口文档编写
自动生成 API 文档的好处不言而喻,它可以提供给你的团队或者外部协作者,方便 API 使用者准确地调用到你的 API。为了降低手动编写文档带来的错误,很多 API 开发者会偏向于寻找一些好的方法来自动生成 API 文档。
Swagger 自动生成 Api 文档:简化接口文档编写

相关产品

  • 云迁移中心