Spring-Boot + Swagger2 自动生成API接口文档-阿里云开发者社区

开发者社区> 开发与运维> 正文
登录阅读全文

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

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

分享: