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

【问题标题】：Create Document from swagger-node-express spec.js and model.js从 swagger-node-express spec.js 和 model.js 创建文档
【发布时间】：2015-05-09 15:59:09
【问题描述】：

resources.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); 
    }
  }
};

model.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 文件。如何从这两个文件生成文档。

【问题讨论】：

标签： node.js swagger swagger-ui

【解决方案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 规范，请将您的 api-docs url 添加到 swagger-ui index.html 文件中：

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

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

【讨论】：