Swagger API文档

接口文档是前后端开发对接时很重要的一个组件。手动编写接口文档既费时,又存在文档不能随代码及时更新的问题,因此产生了像swagger这样的自动生成接口文档的框架。swagger文档一般是随项目代码生成与更新,访问地址也是基于项目地址,因此对项目数不多的团队还好。如果团队的项目很多,比如采用微服务架构的团队,动则几十甚至上百个服务项目,那就意味着前端开发人员需要记住几十甚至上百个swagger文档地址,那就很不友好了。目前貌似还没有较流行的API文档集中化管理项目(也或者是我没找到),因此花了点时间自己集成了一个,介绍如下。

1. swagger-bootstrap-ui项目

该项目是github上的一个开源项目(https://github.com/xiaoymin/swagger-bootstrap-ui ),对swagger ui做了增强,功能整体看起来要丰富一些。来看看效果,

该项目的调试url地址原本是基于自身服务的,我将它改为了注册服务的url地址,以支持注册服务的接口调试。调整后的源码地址: https://github.com/ronwxy/swagger-bootstrap-ui

2. swagger api注册服务

该项目集成了swagger-bootstrap-ui,并提供了swagger api注册接口,接受所有提供了有效配置的服务项目注册,让注册的服务在一个页面上可统一查看,再也不用记太多文档地址了。

启动注册服务后,访问 http://localhost:11090/doc.html 打开文档页面。如上图,可通过下拉列表来选择不同项目,加载项目的接口文档查看或调试。
项目地址: 关注本文最后二维码公众号,回复“swagger”获取源码地址 (一个不只有实战干货的技术公众号,欢迎关注。如果觉得有用,不要吝啬你的star,反正又不要钱,O(∩_∩)O)

3. 服务端配置

在业务服务端,需要提供一些配置。
首先,需要配置一些Bean,如下提供了一个配置类(这里只列出了主要部分,完整代码参考: https://github.com/ronwxy/base-spring-boot)

public class Swagger2AutoConfiguration {

    @Bean
    public Docket restApi() {
        ParameterBuilder builder = new ParameterBuilder();
        builder.name("x-auth-token").description("授权token")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false);
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage(apisBasePackage))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(Collections.singletonList(builder.build()))
                .apiInfo(apiInfo());
    }

    @Profile({"dev"})
    @Bean
    public CommandLineRunner swaggerRegistar(ConfigurableApplicationContext context) {
        return new SwaggerInfoRegistar(context);
    }

    /**
     * use to register swagger api info url to swagger api registry;
     *
     * @author liubo
     */
    public class SwaggerInfoRegistar implements CommandLineRunner {
        @Override
        public void run(String... args) throws Exception {
            String url = buildLocalSwaggerDocsUrl();
            registerLocalSwaggerUrl(url);
        }

        /**
         * register the v2/api-docs url
         *
         * @param url
         */
        private void registerLocalSwaggerUrl(String url) {
            RestTemplate restTemplate = new RestTemplate();
            restTemplate.getMessageConverters().add(new FormHttpMessageConverter());
            MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
            body.add("project", getApiTitle());
            body.add("url", url);
            ResponseEntity<Map> re = restTemplate.postForEntity(getSwaggerRegisterUrl(), body, Map.class);
            if (HttpStatus.OK.equals(re.getStatusCode())) {
                logger.info("swagger api registered success to {}", getSwaggerRegisterUrl());
            } else {
                logger.warn("swagger api registered failed [{}]", re.getBody().get("msg"));
            }
        }
    }

}

该类完成了swagger的基本配置,同时将swagger的/v2/api-docs地址注册到了步骤2中介绍的注册服务。

然后,因为要从注册服务端调用该业务服务的接口进行调试,存在跨域,因此服务需要做跨域支持,配置文件中添加如下定义,

@Bean
@ConditionalOnMissingBean(name = "corsFilterRegistrationBean")
public FilterRegistrationBean corsFilterRegistrationBean() {
    UrlBasedCorsConfigurationSource corsConfigurationSource = new UrlBasedCorsConfigurationSource();

    CorsConfiguration corsConfiguration = new CorsConfiguration();
    corsConfiguration.applyPermitDefaultValues();
    corsConfiguration.setAllowedMethods(Arrays.asList(CorsConfiguration.ALL));
    corsConfiguration.addExposedHeader(HttpHeaders.DATE);

    corsConfigurationSource.registerCorsConfiguration("/**", corsConfiguration);

    CorsFilter corsFilter = new CorsFilter(corsConfigurationSource);
    FilterRegistrationBean filterRegistrationBean = new FilterRegistrationBean();
    filterRegistrationBean.setFilter(corsFilter);
    filterRegistrationBean.setOrder(Ordered.HIGHEST_PRECEDENCE);
    filterRegistrationBean.addUrlPatterns("/*");

    return filterRegistrationBean;
}

最后,在属性配置文件application.yml中配置一些必要的属性,

swagger:
  api-title: Demo标题  #会展示在下拉列表框中,一般写项目名称
  api-description:  Demo描述,集中注册
  group-name: Demo项目
  apis-base-package: cn.jboost.springboot.swagger # API类所在包名
  swagger-registry-path: http://localhost:11090/swagger/register  #就是2中注册服务的注册接口地址

配置完后, 就可以像一般项目一样编写接口类,加swagger注解。项目启动时, 会自动向注册服务完成注册,刷新注册服务的文档页面即可在下拉列表看到。

4. 总结

本文介绍了一个基于swagger ui增强版项目swagger-bootstrap-ui的接口文档集中化管理实现。采用该实现,将所有swagger在线接口文档集中管理,有效提高前后端对接效率。

原文地址:https://www.cnblogs.com/Leo_wl/p/11106098.html

时间: 2024-10-12 05:25:34

Swagger API文档的相关文章

xadmin引入drf-yasg生成Swagger API文档

一.安装drf-yasg: 由于django-rest-swagger已经废弃了 所以引入了drf-yasg pip install drf-yasg 安装install drf-yasg库 https://github.com/axnsan12/drf-yasg Github主页 二.工程的目录结构: demo/settings.py: import os # Build paths inside the project like this: os.path.join(BASE_DIR, ..

Core Web API上使用Swagger提供API文档

在ASP.NET Core Web API上使用Swagger提供API文档 我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页面后,在IISExpress启动Web API站点后,会自动重定向到API文档页面,非常方便.这不仅让我能够快速省查API设计的合理性,同时从API的使用角度也为我自己提供了便捷.下图就是我的博客系统RESTful API

Laravel(PHP)使用Swagger生成API文档不完全指南 - 基本概念和环境搭建 - 简书

在PHPer中,很多人听说过Swagger,部分人知道Swagger是用来做API文档的,然而只有少数人真正知道怎么正确使用Swagger,因为PHP界和Swagger相关的资料实在是太少了.所以鄙人斗胆一试,希望能以本文帮助到大家了解Swagger,从此告别成天用Word.Markdown折腾API文档的日子. 什么是Swagger Swagger is a simple yet powerful representation of your RESTful API. With the lar

基于.NetCore3.1搭建项目系列 —— 使用Swagger导出文档 (番外篇)

前言 回顾之前的两篇Swagger做Api接口文档,我们大体上学会了如何在net core3.1的项目基础上,搭建一套自动生产API接口说明文档的框架. 本来在Swagger的基础上,前后端开发人员在开发生产期间,可以借此进行更加便捷的沟通交流.可是总有些时候,遇到一些难缠的,又不讲道理,偏偏觉得将Swagger文档地址丢给客户会不够正式!死活要一份word文档. 可是这个时候,如果接口数量上百个,甚至更多,一个一个手动输入word,那将是一笔耗时的工作.但却有什么办法可以解决呢? 对了,利用S

Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api

本文作者:小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119 实际项目中非常需要写文档,提高Java服务端和Web前端以及移动端的对接效率. 听说Swagger这个工具,还不错,就网上找了些资料,自己实践了下. 一:Swagger介绍 Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目 实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档,

利用Swagger Maven Plugin生成Rest API文档

利用Swagger Maven Plugin生成Rest API文档 Swagger Maven Plugin This plugin enables your Swagger-annotated project to generate Swagger specs and customizable, templated static documents during the maven build phase. Unlike swagger-core, swagger-maven-plugin

Swagger UI教程 API 文档神器 搭配Node使用

ASP.NET Web API 使用Swagger生成在线帮助测试文档 Swagger 生成 ASP.NET Web API 前言 swagger ui是一个API在线文档生成和测试的利器,目前发现最好用的. 为什么好用?Demo 传送门 支持API自动生成同步的在线文档 这些文档可用于项目内部API审核 方便测试人员了解API 这些文档可作为客户产品文档的一部分进行发布 支持API规范生成代码,生成的客户端和服务器端骨架代码可以加速开发和测试速度 总结一句话就是好用,逼格高.下面我将总结一下如

Swagger UI教程 API 文档神器 搭配Node使用 web api 接口文档 mvc接口文档

两种方案 一.Swagger 配置 web Api 接口文档美化 二.通过NodeJS 发布Swagger UI 配置api 文档 先说一下简单的 Swagger 配置 web Api  Swagger-UI本身只提供在线测试功能,要集成它还需要告诉它本项目提供的各种服务和参数信息.这里就需要一些工作量了,不过好在许多第三方库已经给我们完成了这一工作.我这里用的是Swashbuckle,使用它也比较简单,直接使用Nuget添加其程序包即可: 1.初始化包  PM> Install-Package

API文档自动生成,Swagger的配置

第一步:引用程序集 打开NuGet程序包管理器,搜索Swagger,安装第一个,注意画圈的地方, 已经包含主程序和UI了,安装完成后会在根目录App_Start文件夹下生成SwaggerConfig.cs. 第二步:配置信息 按照如下配置即可,注意命名空间. 1 using System.Web.Http; 2 using WebActivatorEx; 3 using Demo.API; 4 using Swashbuckle.Application; 5 using Swashbuckle.