node.js - 从 swagger-node-express spec.js 和 model.js 创建文档

Question

资源.js

'use strict';
var sw = require('swagger-node-express');
var paramTypes = sw.paramTypes;
var swe = sw.errors;

var petData = require('./service.js');

// the description will be picked up in the resource listing
exports.findById = {
  'spec': {
    description : 'Operations about pets',  
    path : '/pet/{petId}',
    method: 'GET',
    summary : 'Find pet by ID',
    notes : 'Returns a pet based on ID',
    type : 'Pet',
    nickname : 'getPetById',
    produces : ['application/json'],
    parameters : [paramTypes.path('petId', 'ID of pet that needs to be fetched', 'string')],
    responseMessages : [swe.invalid('id'), swe.notFound('pet')]
  },
  'action': function (req,res) {
      console.log('findById call');
    if (!req.params.petId) {
      throw swe.invalid('id'); }
    var id = parseInt(req.params.petId);
    var pet = petData.getPetById(id);

    if(pet) { 
        res.send(JSON.stringify(pet));
    } else { 
        throw swe.notFound('pet', res); 
    }
  }
};

模型.js

exports.models = {
    'Pet':{
      'id':'Pet',
      'required': ['id', 'name'],
      'properties':{
        'id':{
          'type':'integer',
          'format':'int64',
          'description': 'Unique identifier for the Pet',
          'minimum': '0.0',
          'maximum': '100.0'
        },
        'name':{
          'type':'string',
          'description': 'Friendly name of the pet'
        }
      }
    }
  };

您好，我在我的 Node.js 应用程序中使用 swagger-node-express。我已成功配置并且工作正常。

但现在我在使用 swagger-ui 进行记录时遇到问题。swagger-ui 需要 JSON 文件。如何从这两个文件生成文档。

Answer 1

Swagger-node-express 根据您提供的规范生成 json。您只需要通过调用告诉它在哪里发布它

swagger.configureSwaggerPaths('', 'api-docs', '');

在 [yourdomain]/api-docs 发布 json api 描述，例如

localhost:8080/api-docs

当然，您可以将“api-docs”更改为您想要的任何名称。

要使用 swagger-ui 检查您的 api，您需要将其解压到目录中的某个位置。我的位于 ../swagger-ui/dist。告诉express以静态方式提供其中的文件，并给它一个路由，例如/docs:

var dirname = __dirname + '/../swagger-ui/dist/';
var docs_handler = express.static(dirname);
app.get(/^\/docs(\/.*)?$/, function(req, res, next) {
  if (req.url === '/docs') { // express static barfs on root url w/o trailing slash
    res.writeHead(302, { 'Location' : req.url + '/' });
    res.end();
    return;
  }
  // take off leading /docs so that connect locates file correctly
  req.url = req.url.substr('/docs'.length);
  return docs_handler(req, res, next);
});

现在将浏览器指向

localhost:8080/docs

应该显示 swagger-ui 界面。要使 UI 直接显示您的 api 规范，请在 swagger-ui index.html 文件中添加您的 api-docs url:

window.swaggerUi = new SwaggerUi({
    url: "/api-docs",

应该有一种更简洁的方法来进行最后的调整，但我还没有发现。