Wiki.js API文档：Swagger/OpenAPI文档生成

概述

Wiki.js作为现代化的知识管理平台，提供了完整的GraphQL API接口用于内容管理、用户认证、系统配置等操作。虽然Wiki.js原生使用GraphQL而非RESTful API，但我们可以通过技术手段将其转换为符合OpenAPI规范的文档，为开发者提供更加友好的API交互体验。

Wiki.js GraphQL API架构

核心API结构

Wiki.js采用模块化的GraphQL架构，主要包含以下核心模块：

graph TD
    A[Wiki.js GraphQL API] --> B[认证模块]
    A --> C[页面管理模块]
    A --> D[用户管理模块]
    A --> E[系统配置模块]
    A --> F[搜索模块]
    A --> G[存储模块]
    
    B --> B1[用户登录]
    B --> B2[权限验证]
    B --> B3[会话管理]
    
    C --> C1[页面创建]
    C --> C2[内容编辑]
    C --> C3[版本历史]
    C --> C4[标签管理]

主要API端点

模块类别	主要功能	GraphQL操作类型
认证管理	用户登录、注册、令牌管理	Mutation
页面操作	页面CRUD、版本控制、搜索	Query/Mutation
用户管理	用户信息、权限配置	Query/Mutation
系统配置	站点设置、主题管理	Query/Mutation
文件存储	资源上传、下载管理	Mutation/Query

GraphQL Schema转换为OpenAPI

转换策略

由于Wiki.js使用GraphQL，我们需要通过以下步骤将其转换为OpenAPI规范：

1. Schema解析：解析GraphQL schema定义
2. 类型映射：将GraphQL类型映射为OpenAPI Schema
3. 端点转换：将GraphQL查询转换为RESTful端点
4. 认证集成：处理GraphQL认证指令

示例转换代码

const { buildSchema } = require('graphql');
const { graphqlToOpenApi } = require('@graphql-to-openapi/converter');

// Wiki.js GraphQL Schema示例
const wikiSchema = `
type Query {
  pages: PageQuery
  users: UserQuery
  system: SystemQuery
}

type PageQuery {
  list(limit: Int, tags: [String!]): [PageListItem!]!
  single(id: Int!): Page
  search(query: String!): PageSearchResponse!
}

type Page {
  id: Int!
  title: String!
  content: String!
  path: String!
  locale: String!
}
`;

// 转换为OpenAPI
async function convertToOpenAPI() {
  const schema = buildSchema(wikiSchema);
  const openApiDocument = await graphqlToOpenApi(schema, {
    title: 'Wiki.js API',
    version: '2.0.0'
  });
  
  return openApiDocument;
}

OpenAPI文档生成方案

方案一：使用graphql-to-openapi工具

# 安装转换工具
npm install @graphql-to-openapi/converter graphql

# 生成OpenAPI文档
const converter = require('@graphql-to-openapi/converter');
const fs = require('fs');

const schema = loadWikiJsSchema(); // 加载Wiki.js schema
const openApiSpec = converter.convert(schema, {
  info: {
    title: "Wiki.js API",
    version: "2.0.0",
    description: "OpenAPI documentation for Wiki.js GraphQL API"
  }
});

fs.writeFileSync('wiki-openapi.json', JSON.stringify(openApiSpec, null, 2));

方案二：自定义转换器

class WikiJsOpenAPIConverter {
  constructor(graphqlSchema) {
    this.schema = graphqlSchema;
    this.openApiSpec = {
      openapi: "3.0.0",
      info: {
        title: "Wiki.js API",
        version: "2.0.0",
        description: "RESTful API documentation for Wiki.js GraphQL endpoints"
      },
      servers: [
        { url: "https://your-wiki-instance.com", description: "Production server" }
      ],
      paths: {},
      components: {
        schemas: {},
        securitySchemes: {
          bearerAuth: {
            type: "http",
            scheme: "bearer",
            bearerFormat: "JWT"
          }
        }
      }
    };
  }

  convertQueryToEndpoint(queryName, queryType) {
    // 实现GraphQL查询到REST端点的转换逻辑
    const path = `/api/${queryName.toLowerCase()}`;
    this.openApiSpec.paths[path] = {
      get: {
        summary: `Execute ${queryName} query`,
        operationId: queryName,
        parameters: this.buildParameters(queryType),
        responses: {
          "200": {
            description: "Successful response",
            content: {
              "application/json": {
                schema: this.buildResponseSchema(queryType)
              }
            }
          }
        },
        security: [{ bearerAuth: [] }]
      }
    };
  }

  buildParameters(queryType) {
    // 构建查询参数
    const parameters = [];
    const fields = this.schema.getType(queryType).getFields();
    
    for (const [fieldName, field] of Object.entries(fields)) {
      if (fieldName !== 'responseResult') {
        parameters.push({
          name: fieldName,
          in: "query",
          required: !field.type.toString().includes('!'),
          schema: this.mapGraphQLTypeToOpenAPI(field.type)
        });
      }
    }
    
    return parameters;
  }
}

认证与权限管理

JWT认证集成

Wiki.js使用JWT（JSON Web Token）进行认证，需要在OpenAPI文档中正确配置：

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      
security:
  - bearerAuth: []

权限级别映射

GraphQL权限	OpenAPI安全要求	描述
@auth(requires: ["read:pages"])	read:pages	页面读取权限
@auth(requires: ["write:pages"])	write:pages	页面写入权限
@auth(requires: ["manage:system"])	manage:system	系统管理权限

API文档部署与使用

本地开发环境

# 使用Redoc渲染OpenAPI文档
npx redoc-cli serve wiki-openapi.json

# 或使用Swagger UI
npx swagger-ui-watcher wiki-openapi.json

生产环境集成

// 在Wiki.js中集成API文档端点
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');

const app = express();
const openApiDocument = YAML.load('wiki-openapi.yaml');

// 添加API文档路由
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(openApiDocument));

// 启动服务器
app.listen(3000, () => {
  console.log('API docs available at http://localhost:3000/api-docs');
});

最佳实践与注意事项

1. 版本控制策略

info:
  title: Wiki.js API
  version: 2.0.0
  description: |
    This API documentation is automatically generated from 
    Wiki.js GraphQL schema. 
    
    **Note**: Some GraphQL-specific features may not be fully 
    represented in this RESTful documentation.

2. 错误处理规范

components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        errorCode:
          type: integer
          description: HTTP status code
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details

3. 性能优化建议

• 使用缓存机制减少schema解析开销
• 实现增量更新避免全量重新生成
• 提供文档压缩版本减少传输大小

总结

通过将Wiki.js的GraphQL API转换为OpenAPI规范，我们可以：

1. 统一文档标准：遵循行业标准的OpenAPI规范
2. 改善开发体验：提供熟悉的RESTful API文档界面
3. 增强工具集成：支持各种API测试和监控工具
4. 促进团队协作：标准化API设计和文档流程

虽然GraphQL和RESTful有不同的设计哲学，但通过适当的转换策略，我们可以在保持Wiki.js强大功能的同时，为开发者提供更加友好和熟悉的API文档体验。