Índice
5. Resolva o problema de que a nova versão não pode transmitir parâmetros
5. Como usar o parâmetro Authorization para passar o token no cabeçalho da nova versão
Recentemente, aprendi a usar o Node para construir um serviço de interface em segundo plano. Pensei em usar o swagger-ui para gerar documentos de depuração de interface e consultei informações relevantes na Internet. O processo de instalação ou processo de uso não é escrito com muitos detalhes. É um pouco hostil para iniciantes, especialmente aqueles que estão apenas começando com a programação em segundo plano, então vou resumir alguns métodos envolvidos no meu processo de uso.
1. Instalação
Este artigo usa a combinação de swagger-jsdoc e swagger-ui-express para gerar documentos de interface swagger-ui. Portanto, instale esses dois módulos primeiro.
npm install --save-dev swagger-jsdoc
npm install --save-dev [email protected]Deve-se observar que a swagger-ui-express recomenda o uso da versão 2.0.8, embora a versão mais recente deste módulo seja a V4.0.x. Como o blogueiro descobriu no processo de uso que a versão maior que 2.0.8 e superior, os dados no corpo não puderam ser transmitidos, o comprimento do conteúdo sempre foi 0 e há alguns problemas ao personalizar o cabeçalho. Posteriormente, o host foi ao GitHub para verificar os problemas [ clique para pular ], e verifiquei de acordo com a solução proposta nele. O código do host está bom, mas ainda não pode ser resolvido. Finalmente, faça o downgrade do swagger-ui-express para 2.0.8 antes que ele possa ser usado normalmente. Então é recomendado usar essa versão aqui, claro, se você não tiver problema em usar a versão mais recente, também é possível.
2. Configuração
Configure as informações básicas do swagger e especifique o local onde o arquivo de interface está armazenado
const swaggerUi = require('swagger-ui-express');
const swaggerJSDoc = require('swagger-jsdoc');
const path = require('path');
const config = require('../config/default');
const options = {
definition: {
// swagger 采用的 openapi 版本 不用改
openapi: '3.0.3',
// swagger 页面基本信息 自由发挥
info: {
title: '后台管理系统接口',
version: '创建时间：2020年3月27日',
}
},
apis: [ path.join(__dirname, '../router/*.js') ]//这里指明接口路由存放的文件夹。楼主放在根路径的router下
}
const swaggerSpec = swaggerJSDoc(options)
module.exports = (app) => {
if(config.ENV === 'Dev'){
// 开放 swagger 相关接口，
app.get('/swagger.json', function(req, res) {
res.setHeader('Content-Type', 'application/json');
res.send(swaggerSpec);
});
// 使用 swaggerSpec 生成 swagger 文档页面，并开放在指定路由
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
}
}
3. Escreva comentários
Escreva as anotações da interface de acordo com as especificações. Para especificações específicas, você pode visualizar este site [ clique para pular ]. Uma observação especial aqui: cuidado com reduções e camadas. Caso contrário, haverá problemas ao construí-lo.
// 这里给出楼主项目里的注释代码
// 定义参数
/**
* @swagger
* definition:
* noticeAddParams:
* description: 通知添加参数
* properties:
* title:
* type: string
* content:
* type: string
* endTime:
* type: string
*/
// 定义接口
/**
* @swagger
* /admin/notice/add:
* post:
* tags:
* - 管理员
* description: 通知添加
* consumes:
* - application/json
* - application/xml
* produces:
* - application/json
* - application/xml
* parameters:
* - name: Authorization
* in: header
* required: false
* - name: body
* in: body
* schema:
* $ref: '#/definitions/noticeAddParams'
* responses:
* 200:
* description: 发布成功
* 402:
* description: 信息填写不全
* 403:
* description: 参数类型错误
*
*/4. Comece.
Nó inicial. IP de acesso: porta/api-docs. Em seguida, você pode ver a interface que escreveu e também pode executar a depuração relacionada.
O efeito é o seguinte:
-------------------------------------------------------Linha de Separação 2020-04-27 14:39:18-----------------------------------------------------------------
5. Resolva o problema de que a nova versão não pode transmitir parâmetros
Alguém respondeu a um problema que postei no GitHub hoje, Portal . Se swagger-ui-express for maior que 2.0.8, você precisa usar a especificação openapi3.x para escrever comentários, e se for menor que 2.0.8, você pode usar a versão openapi2.x. As versões 3.x não são compatíveis com 2.x. A razão é que requestBody é usado como o corpo da transmissão de dados em 3.x, enquanto o parâmetro paramters é usado em 2.x. As notas da nova versão são dadas abaixo:
/**
* @swagger
* /user/login:
* post:
* tags:
* - 用户
* description: 登录系统
* requestBody:
* required: true
* content:
* application/json:
* schema:
* $ref: '#/definitions/loginInfo'
* responses:
* 200:
* description: 登录成功，返回token和用户信息
*
*/Dê comentários legados.
/**
* @swagger
* /user/login:
* post:
* tags:
* - 用户
* description: 登录系统
* consumes:
* - application/json
* - application/xml
* produces:
* - application/json
* - application/xml
* parameters:
* - name: body
* in: body
* required: true
* schema:
* $ref: "#/definitions/loginInfo"
* responses:
* 200:
* description: 登录成功，返回token和用户信息
*
*/Referindo-se aos dois trechos de código acima, pode-se descobrir que a nova versão do corpo precisa ser colocada em requestBody em vez de parâmetros. Existem muitos usos de requestBody, você pode consultar o endereço no portal para visualizar.
5. Como usar o parâmetro Authorization para passar o token no cabeçalho da nova versão
Na especificação openapi3.x, o parâmetro Authorization é ocupado por OpenAPI. Se você usar esse parâmetro como o cabeçalho da solicitação, descobrirá que, ao acionar a solicitação, o parâmetro Authorization não será carregado no cabeçalho. Se você não usar esse parâmetro, poderá carregá-lo. E se eu precisar usar esse parâmetro como o parâmetro de carregamento do token?
Dê as respostas sobre os problemas primeiro. Portal 1 , Portal 2 . Talvez você o veja em uma nuvem, mas darei minha solução abaixo.
1), primeiro use a anotação de componentes para declarar o securitySchemes global. Os parâmetros específicos são explicados em detalhes no Portal 2.
/**
* @swagger
* components:
* securitySchemes:
* ApiKeyAuth: // 名称
* type: apiKey // 类型
* in: header // 位置
* name: Authorization // 参数
*/2) Remova a declaração do cabeçalho nos parâmetros originais. Se você declarar apenas o parâmetro Autorização, remova a declaração.Se houver outros parâmetros, remova apenas a Autorização.
3) Consulte estas declarações de segurança. Você pode referenciá-lo globalmente ou em anotações de API. É recomendável usar este último, e você pode controlá-lo de acordo com suas próprias necessidades.
/**
* @swagger
* /user/login:
* post:
* tags:
* - 用户
* description: 登录系统
* security:
* - ApiKeyAuth: []
* requestBody:
* required: true
* content:
* application/json:
* schema:
* $ref: '#/definitions/loginInfo'
* responses:
* 200:
* description: 登录成功，返回token和用户信息
*
*/4) Após declarar, execute o projeto. Você descobrirá que há um cadeado por trás da API que adicionou segurança e um botão também aparece no canto superior direito do documento.
5) Clique no botão superior direito ou no cadeado atrás da API e uma caixa aparecerá solicitando que você insira o valor de autorização. Depois de inserir de acordo com os prompts, clique em OK e o gráfico de bloqueio muda de um estado aberto para um estado fechado. Neste momento, você está acionando sua solicitação de API e descobrirá que o swagger adiciona o valor de autorização que você inseriu agora.
Como você pode ver na figura acima, nos parâmetros, não adicionei o campo de cabeçalho Authorization, mas o entreguei à autenticação de segurança integrada do OAS3 para processamento. Claro, se você não usar esse parâmetro, é muito simples e o processamento é o seguinte.
/**
* @swagger
* /admin/notice/add:
* post:
* tags:
* - 管理员
* description: 通知添加
* parameters:
* - in: header
* name: x-http-token
* requestBody:
* required: true
* content:
* application/json:
* schema:
* $ref: '#/definitions/noticeAddParams'
* responses:
* 200:
* description: 获取成功
*
*/