Swagger擴展開發中任意架構實現Swagger Doc注冊的示例分析

這篇文章給大家介紹Swagger擴展開發中任意架構實現Swagger Doc注冊的示例分析，內容非常詳細，感興趣的小伙伴們可以參考借鑒，希望對大家能有所幫助。

緣起：公司08年以前的老項目，跟著迭代了一個版本，架構太老自己干著也受氣。于是提議升級為SpringBoot 這種新的能好受一點。但是老接口太多，老接口是通過自定義實現的Servlet，按照掃描Bean 函數通過反射的方式調用。也不想把所有接口都轉為新的，舊接口前端要 Swagger 沒辦法，硬著頭皮上。

查了大量資料，都是 SpringBoot 集成 Swagger，重復、簡單技術含量很低，沒找到我想要的。

首先把項目一通整合，一通重構支持了 SpringBoot，通過SpringBoot 啟動，并且集成了Swagger，新寫的RESTAPI 都支持Swagger。現在需要掃描舊接口，生成Swagger。

1. 實現一個Spring ApplicationListener，在Spring ApplicationContext 初始化完成后調用，用于生成舊接口的Swagger 掃描。

@Repository
public class SwaggerExtentionSupport implements ApplicationListener<ContextRefreshedEvent> {
    @Override
    public void onApplicationEvent(ContextRefreshedEvent event) {
        // Spring 框架加載完全后，掃描 bean，獲取 servlet
        initSwagger(event.getApplicationContext());
    }
}

2. 注入 DocumentationCache

 @Autowired
DocumentationCache documentationCache;

// Swagger 默認是 Default，就接口我們放到自定義的 group 下
@Value("${swagger.group}")
private String groupName;

通過 Debug，發現新實現的SpringBoot接口，構造的如下：

3. 開始掃描接口

private void initSwagger(ApplicationContext context) {
    Documentation documentation = documentationCache.documentationByGroup(groupName);
    if(documentation == null) {
        // 如果 groupName 指定的下沒有，則掛載 default 上
        documentation = documentationCache.documentationByGroup(Docket.DEFAULT_GROUP_NAME);
    }
    if (documentation != null) {
        // 取得所有的 API 合集
        Multimap<String, ApiListing> apiListings = documentation.getApiListings();
        Class[] clazzs = ... //Scan Classes
        for (Class<?> aClass : clazzs) {
            log.info("add swagger bean {}", aClass.getSimpleName());
            Method[] servletMethods = aClass.getDeclaredMethods();
            for (Method servletMethod : servletMethods) {
                String methodName = servletMethod.getName();
                // 獲得接口名稱，必須符合是API接口，且方法是 public
                if(validSwagger(methodName) && Modifier.isPublic(servletMethod.getModifiers())) {
                    // 返回 tags
                    Set<Tag> tags = addApi(apiListings, documentation.getBasePath(), name, methodName);
                    if(!tags.isEmpty()) {
                        documentation.getTags().addAll(tags);
                    }
                }
            }
            log.info("swagger apis size: {}", apiListings.size());
        }
    }
}

4. 把掃描到合法的添加到Swagger

private Set<Tag> addApi(Multimap<String, ApiListing> apiListings,
                            String basePath,
                            String beanName,
                            String methodName) {
    // 獲取名稱, 去除后綴
    String optGroup = getName(beanName);
    String apiId = optGroup + "_" + methodName; // 全局唯一
    String optId = methodName;

    // 采用 apiID，檢測是否唯一，后續加到同一個tag下
    Collection<ApiListing> apis = apiListings.get(apiId);
    if(apis == null) {
        // 后面只是用 apis 的 size 獲取長度
        apis = new HashSet<>();
    }

    ArrayList<ApiDescription> apis1 = new ArrayList<>();
    ArrayList<Operation> operations = new ArrayList<>();

    ResponseMessage v200 = new ResponseMessageBuilder().code(200).message("OK").build();
    ResponseMessage v401 = new ResponseMessageBuilder().code(401).message("Unauthorized").build();
    ResponseMessage v403 = new ResponseMessageBuilder().code(403).message("Forbidden").build();
    ResponseMessage v404 = new ResponseMessageBuilder().code(404).message("Not Found").build();

    // tag，Swagger 首頁展示的都是tag，tag下掛載的是接口
    HashSet<Tag> tags = new HashSet<>();

    // description 是生成 API JS 的文件名
    // optGroup 是生成的函數名
    Tag tag = new Tag(optGroup, optGroup + "Controller");
    tags.add(tag);
    
    //暫時先不要參數
    ArrayList<Parameter> parameters = new ArrayList<>();
   
    // 注意 position，必須是不重復的值,數值 0-n
    // Operation 只需要 tag name，他決定了該 api 在 Swagger 上掛載的tag
    Operation operaGet = new Operation(
                HttpMethod.GET,
                "do exec " + optGroup + "." + methodName,
                "",
                new ModelRef("string"),
                optId+"UsingGET",
                0,
                Sets.newHashSet(tag.getName()),
                Sets.newHashSet(MediaType.ANY_TYPE.toString()),
                Sets.newHashSet(MediaType.create("application", "json").toString()),
                new HashSet<>(),
                new ArrayList<>(),
                parameters,
                Sets.newHashSet(v200, v401, v403, v404),
                "",
                false,
                new ArrayList<>()
        );

    operations.add(operaGet);
    //operations.add(operaPost);

    String url = "/" + beanName + "?invoke=" + methodName;
    apis1.add(new ApiDescription(groupName,
                url,
                beanName+"." + methodName,
                operations, false));

    // 注意 position，必須是不重復的值，這里我用 apis.size()
    ApiListing apiListing = new ApiListing(
                API_VER,
                basePath,
                "/" + beanName,
                new HashSet<>(),new HashSet<>(),"", new HashSet<>(), new ArrayList<>(),
                apis1,
                new HashMap<>(), beanName+"." + methodName, apis.size(), tags);

    // 放到api列表中
    apiListings.put(apiId, apiListing);

    // 返回 tag，tag 會顯示到 Swagger Content
    return tags;
}

生成 Swagger 效果如：

關于Swagger擴展開發中任意架構實現Swagger Doc注冊的示例分析就分享到這里了，希望以上內容可以對大家有一定的幫助，可以學到更多知識。如果覺得文章不錯，可以把它分享出去讓更多的人看到。