Entrada de função : aplicativo de gerenciamento de API / selecionar um item / outros menus / sincronização de fonte de dados (documentos de API são gerados automaticamente)
Esta função pode gerar documentos de API automaticamente com base nas informações de API da fonte de dados, configurando as informações da fonte de dados.
Atualmente suporta 5 fontes de dados: Swagger URL, apiDoc, Github, gitlab, code cloud .
URL Swagger e fonte de dados apiDoc
O método de configuração da fonte de dados do Swagger URL e apiDoc é o mesmo, você só precisa preencher o nome da fonte e o endereço de acesso do arquivo json.
-
análise de campo
-
Nome da fonte: O nome usado para identificar a fonte, inserir um nome não afeta o efeito de sincronização.
-
endereço de acesso ao arquivo json: Swagger URL ou endereço Json gerado por apiDoc. Observe que o endereço deve ser acessível por meio da rede e o endereço deve ser capaz de retornar dados do tipo JSON, caso contrário, ele solicitará que o endereço não possa ser acessado.
Gitlab e github e fonte de dados de nuvem de código
A configuração da fonte de dados da classe do armazém de código é relativamente complicada. O sistema lerá remotamente o código no armazém e gerará automaticamente o documento API correspondente de acordo com o formato de anotação de código do Swagger 2.0.
-
análise de campo
-
Os campos de configuração da fonte de dados de cada tipo de armazém de código são analisados da seguinte forma:
GitHub
| item de configuração | ilustrar |
| tipo de repositório de código | Escolha Github |
| Endereço do depósito de código | Preencha o GitHub por padrão: vamos construir a partir daqui GitHub |
| nome de usuário | Nome da conta do Github |
| nome do armazém | Nome do armazém do repositório Github |
| acessar chave privada | Os tokens privados do Warehouse são gerados em Configurações->Configurações do desenvolvedor->Tokens de acesso pessoal do Repositório GitHub |
| ramificar para digitalizar | O padrão é o branch master, você também pode escolher o branch de código que realmente precisa ser escaneado |
| Caminho do diretório da API a ser verificado | Caminho de armazenamento do código relacionado à camada de API |
| O caminho do diretório da estrutura de dados que precisa ser verificado | Caminho de armazenamento de informações de configuração relacionadas à estrutura de dados |
| Idioma alvo | Java ou PHP |
| Formato de anotação | O padrão é Swagger 2.0. Para o formato de comentários de código, consulte o seguinte formato ou consulte o documento oficial swagger-php/Examples em 2f66ec81d2bc4b82c26b250b187d5e9ea07b0538 · zircote/swagger-php · GitHub |
| Método de sincronização de dados | Atualmente, existem três opções: atualização incremental, atualização completa e apenas adicionar novas APIs. A plataforma de gerenciamento de P&D de APIs recomenda atualização incremental. Após cada sincronização, o sistema irá gerar automaticamente a versão histórica da API para facilitar os documentos de rollback, então não se preocupe mesmo se errar. |
| O estado padrão para gerar a documentação da API | O estado padrão da API recém-adicionada obtida por verificação, o padrão é o estado ativado |
GitLabGenericName
| item de configuração | ilustrar |
| tipo de repositório de código | Escolha o Gitlab |
| Endereço do depósito de código | GitLab versão on-line com fio e os usuários criam sua própria versão de nuvem privada. A versão on-line pode preencher a plataforma DevSecOps | GitLab . Se for o GitLab implantado por você, escreva o nome de domínio ou a porta IP |
| ID do projeto | IDs de projeto no GitLab |
| acessar chave privada | Pode ser obtido através da função Access Tokens do GitLab |
| ramificar para digitalizar | O padrão é o branch master, você também pode escolher o branch de código que realmente precisa ser escaneado |
| Caminho do diretório da API a ser verificado | O caminho de armazenamento dos códigos relacionados à camada API, por exemplo: src/main/java/com/example/demo/controller |
| O caminho do diretório da estrutura de dados que precisa ser verificado | Caminho de armazenamento de informações de configuração relacionadas à estrutura de dados, por exemplo: src/main/java/com/example/demo/model |
| Idioma alvo | Java ou PHP |
| Formato de anotação | O padrão é Swagger 2.0. Para o formato de comentários de código, consulte o seguinte formato ou consulte o documento oficial swagger-php/Examples em 2f66ec81d2bc4b82c26b250b187d5e9ea07b0538 · zircote/swagger-php · GitHub |
| Método de sincronização de dados | Atualmente, existem três opções: atualização incremental, atualização completa e apenas adicionar novas APIs. A plataforma de gerenciamento de P&D de APIs recomenda atualização incremental. Após cada sincronização, o sistema irá gerar automaticamente a versão histórica da API para facilitar os documentos de rollback, então não se preocupe mesmo se errar. |
| O estado padrão para gerar a documentação da API | O estado padrão da API recém-adicionada obtida por verificação, o padrão é o estado ativado |
nuvem de código
| item de configuração | ilustrar |
| tipo de repositório de código | Escolha a nuvem de código |
| Endereço do depósito de código | O URL de acesso do armazém do projeto, como Gitee - plataforma de eficiência de P&D DevOps de nível empresarial |
| nome do espaço | O nome do espaço que você criou no Code Cloud, como eolinker |
| nome do armazém | O nome do armazém no espaço, como goku |
| acessar chave privada | Token privado do Code Cloud |
| ramificar para digitalizar | O padrão é o branch master, você também pode escolher o branch de código que realmente precisa ser escaneado |
| Caminho do diretório da API a ser verificado | Caminho de armazenamento do código relacionado à camada de API |
| O caminho do diretório da estrutura de dados que precisa ser verificado | Caminho de armazenamento de informações de configuração relacionadas à estrutura de dados |
| Idioma alvo | Java ou PHP |
| Formato de anotação | O padrão é Swagger 2.0. Para o formato de comentários de código, consulte o seguinte formato ou consulte o documento oficial swagger-php/Examples em 2f66ec81d2bc4b82c26b250b187d5e9ea07b0538 · zircote/swagger-php · GitHub |
| Método de sincronização de dados | Atualmente, existem três opções: atualização incremental, atualização completa e apenas adicionar novas APIs. A plataforma de gerenciamento de P&D de APIs recomenda atualização incremental. Após cada sincronização, o sistema irá gerar automaticamente a versão histórica da API para facilitar os documentos de rollback, então não se preocupe mesmo se errar. |
| O estado padrão para gerar a documentação da API | O estado padrão da API recém-adicionada obtida por verificação, o padrão é o estado ativado |
configuração de sincronização
Depois de concluir a configuração da fonte de dados, você precisa configurar a lógica de negócios de sincronização.
Método de sincronização de dados
Suporta três métodos de sincronização: atualização incremental, atualização completa e apenas adicionando novas APIs
-
atualização incremental
-
Ao atualizar os dados, julgue se a API e o conteúdo da API foram alterados e sincronize apenas a parte alterada. Como adicionar novas APIs e modificar o conteúdo alterado da API. Aplicável à maioria das situações, escolha este método quando não souber como evitar a perda de dados.
-
Como a comparação incremental é necessária, ao selecionar a atualização incremental, você precisa selecionar um identificador exclusivo para avaliar a API. Três métodos podem ser selecionados: identificação da interface (operationId), endereço da interface combinado com o modo de solicitação e nome da interface.
-
atualização completa
-
Ao atualizar os dados, limpe todas as APIs no projeto existente e reimporte as informações da API da fonte de dados. Observe que esse método causará a perda do conteúdo da API editado anteriormente e só é aplicável para reimportar todas as informações da API em um pequeno número de casos.
-
Adicionar apenas nova API
-
Ao atualizar os dados, determine se há uma nova API, se houver uma nova API, adicione uma nova API, mas não excluirá a API que não existe e não atualizará o conteúdo do documento da API existente.
Configurações de status e novo agrupamento de documentos
Independentemente do método de sincronização de dados escolhido, você pode configurar o status do documento recém-gerado e o status do documento alterado separadamente. A opção de status é o status de todos os documentos da API.
Também podemos definir a qual grupo os documentos recém-gerados serão adicionados e o padrão é o diretório raiz.