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
目录
相关文章
|
1月前
|
安全 Java API
第7章 Spring Security 的 REST API 与微服务安全(2024 最新版)(上)
第7章 Spring Security 的 REST API 与微服务安全(2024 最新版)
76 0
第7章 Spring Security 的 REST API 与微服务安全(2024 最新版)(上)
|
1月前
|
数据可视化 Linux API
如何在Linux使用docker部署Swagger Editor并实现无公网IP远程协同编辑API文档
如何在Linux使用docker部署Swagger Editor并实现无公网IP远程协同编辑API文档
|
1月前
|
监控 Java API
Spring cloud Hystrix 、Dashboard、API(zuul)相关报错
Spring cloud Hystrix 、Dashboard、API(zuul)相关报错
30 2
|
4天前
|
负载均衡 Java API
Spring Cloud Gateway 详解:构建高效的API网关解决方案
Spring Cloud Gateway 详解:构建高效的API网关解决方案
11 0
|
6天前
|
Java API 网络架构
【Spring Boot】详解restful api
【Spring Boot】详解restful api
10 0
|
8天前
|
Java API 开发者
Java一分钟之-Spring Cloud Gateway:API网关
【6月更文挑战第10天】Spring Cloud Gateway是Spring Cloud生态中的API网关组件,基于Spring Framework 5、Reactor和Spring Boot 2.0,支持响应式编程。它提供路由转发、过滤器链(包括预处理、路由和后处理)和断言功能。快速入门涉及添加相关依赖和配置路由规则。常见问题包括路由冲突、过滤器顺序和性能瓶颈。通过动态路由和过滤器示例,展示了其灵活性。Spring Cloud Gateway是微服务架构的有力工具,可提升系统稳定性和开发效率。
118 0
|
11天前
|
XML 前端开发 Java
Spring3 MVC中使用Swagger生成API文档
Spring3 MVC中使用Swagger生成API文档
12 0
|
11天前
|
JSON 前端开发 API
Apache HttpClient调用Spring3 MVC Restful Web API演示
Apache HttpClient调用Spring3 MVC Restful Web API演示
12 1
|
23天前
|
Java API Spring
Spring Boot中的 6 种API请求参数读取方式
本文介绍了Spring Boot中6种常见的请求参数读取方式:@RequestParam用于加载URL查询参数,@PathVariable处理RESTful风格的URL路径参数,@MatrixVariable处理URL路径中的矩阵变量,@RequestBody用于读取POST/PUT请求的复杂请求体,@RequestHeader加载请求头信息,而@CookieValue则用于获取Cookie值。这些注解在不同场景下满足了API参数的多样化需求。
|
25天前
|
API
1天搞定SpringBoot+Vue全栈开发 (2)RESTful API与Swagger
1天搞定SpringBoot+Vue全栈开发 (2)RESTful API与Swagger