From 19c116a4e1f8fb543003dfc2d8fc02613b533d98 Mon Sep 17 00:00:00 2001 From: Benjamin Goetz Date: Thu, 29 Nov 2018 14:51:21 +0100 Subject: [PATCH 1/2] Add host, basePath and schemes to the output file and make them configurable through the apidoc.json file --- lib/index.js | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/lib/index.js b/lib/index.js index dc080a2..8b9ea80 100644 --- a/lib/index.js +++ b/lib/index.js @@ -90,7 +90,10 @@ function createApidocSwagger(options) { }); apidoc.setLogger(app.log); apidoc.setMarkdownParser(app.markdown); - apidoc.setPackageInfos(packageInfo.get()); + + var packageInfos = packageInfo.get(); + + apidoc.setPackageInfos(packageInfos); api = apidoc.parse(app.options); @@ -104,7 +107,13 @@ function createApidocSwagger(options) { if (app.options.parse !== true){ var apidocData = JSON.parse(api.data); var projectData = JSON.parse(api.project); - api["swaggerData"] = JSON.stringify(apidocSwagger.toSwagger(apidocData , projectData)); + var swaggerData = apidocSwagger.toSwagger(apidocData , projectData); + + swaggerData.host = packageInfos.host || '{{url}}'; + swaggerData.basePath = packageInfos.basePath || ''; + swaggerData.schemes = packageInfos.schemes || ['http']; + + api["swaggerData"] = JSON.stringify(swaggerData); createOutputFile(api); } From 3f35e852d54f27167b10dc6cb369fa3bb4171705 Mon Sep 17 00:00:00 2001 From: Benjamin Goetz Date: Thu, 29 Nov 2018 14:51:29 +0100 Subject: [PATCH 2/2] Add request examples, responses and refactor the parameters management --- lib/apidocToSwagger.js | 132 ++++++++++++++++++++++++++++------------- 1 file changed, 90 insertions(+), 42 deletions(-) diff --git a/lib/apidocToSwagger.js b/lib/apidocToSwagger.js index 89c6380..2ad591f 100644 --- a/lib/apidocToSwagger.js +++ b/lib/apidocToSwagger.js @@ -80,19 +80,42 @@ function createPostPushPutOutput(verbs, definitions, pathKeys) { }); params = params.concat(pathParams); - var required = verbs.parameter && verbs.parameter.fields && + var required = verbs.parameter && verbs.parameter.fields && verbs.parameter.fields.Parameter && verbs.parameter.fields.Parameter.length > 0; + var examples = _.get(verbs, 'parameter.examples'); - params.push({ + if (examples) { + var requestExample = _.find(examples, {title: 'Request-Example:'}); + + if (requestExample) { + var description = requestExample.content; + } + } + + if (verbDefinitionResult.topLevelParametersRef !== null) { + params.push({ "in": "body", "name": "body", - "description": removeTags(verbs.description), + "description": typeof description === 'undefined' ? removeTags(verbs.description) : description, "required": required, "schema": { "$ref": "#/definitions/" + verbDefinitionResult.topLevelParametersRef } }); - + } + + var responses = {}; + + if (_.has(verbs, 'success.examples[0]')) { + var successExamples = _.get(verbs, 'success.examples'); + + successExamples.forEach(successExample => { + responses[successExample.title] = { + "description": successExample.content + }; + }) + } + pathItemObject[verbs.type] = { tags: [verbs.group], summary: removeTags(verbs.description), @@ -102,23 +125,24 @@ function createPostPushPutOutput(verbs, definitions, pathKeys) { produces: [ "application/json" ], - parameters: params + parameters: params, + responses: responses } if (verbDefinitionResult.topLevelSuccessRef) { pathItemObject[verbs.type].responses = { - "200": { - "description": "successful operation", - "schema": { - "type": verbDefinitionResult.topLevelSuccessRefType, - "items": { - "$ref": "#/definitions/" + verbDefinitionResult.topLevelSuccessRef - } - } - } - }; + "200": { + "description": "successful operation", + "schema": { + "type": verbDefinitionResult.topLevelSuccessRefType, + "items": { + "$ref": "#/definitions/" + verbDefinitionResult.topLevelSuccessRef + } + } + } + }; }; - + return pathItemObject; } @@ -132,12 +156,12 @@ function createVerbDefinitions(verbs, definitions) { var fieldArrayResult = {}; if (verbs && verbs.parameter && verbs.parameter.fields) { - fieldArrayResult = createFieldArrayDefinitions(verbs.parameter.fields.Parameter, definitions, verbs.name, defaultObjectName); + fieldArrayResult = createFieldArrayDefinitions(verbs.parameter.fields.Parameter, definitions, verbs.name, defaultObjectName); result.topLevelParametersRef = fieldArrayResult.topLevelRef; }; if (verbs && verbs.success && verbs.success.fields) { - fieldArrayResult = createFieldArrayDefinitions(verbs.success.fields["Success 200"], definitions, verbs.name, defaultObjectName); + fieldArrayResult = createFieldArrayDefinitions(verbs.success.fields["Success 200"], definitions, verbs.name, defaultObjectName); result.topLevelSuccessRef = fieldArrayResult.topLevelRef; result.topLevelSuccessRefType = fieldArrayResult.topLevelRefType; }; @@ -171,7 +195,7 @@ function createFieldArrayDefinitions(fieldArray, definitions, topLevelRef, defau nestedName.propertyName = null; } else if (parameter.type == "Array") { objectName = nestedName.propertyName; - nestedName.propertyName = null; + nestedName.propertyName = null; result.topLevelRefType = "array"; } result.topLevelRef = objectName; @@ -235,6 +259,19 @@ function createGetDeleteOutput(verbs,definitions) { verbs.type = verbs.type === "del" ? "delete" : verbs.type; var verbDefinitionResult = createVerbDefinitions(verbs,definitions); + + var responses = {}; + + if (_.has(verbs, 'success.examples[0]')) { + var successExamples = _.get(verbs, 'success.examples'); + + successExamples.forEach(successExample => { + responses[successExample.title] = { + "description": successExample.content + }; + }) + } + pathItemObject[verbs.type] = { tags: [verbs.group], summary: removeTags(verbs.description), @@ -244,20 +281,21 @@ function createGetDeleteOutput(verbs,definitions) { produces: [ "application/json" ], - parameters: createPathParameters(verbs) + parameters: createPathParameters(verbs), + responses: responses } if (verbDefinitionResult.topLevelSuccessRef) { pathItemObject[verbs.type].responses = { - "200": { - "description": "successful operation", - "schema": { - "type": verbDefinitionResult.topLevelSuccessRefType, - "items": { - "$ref": "#/definitions/" + verbDefinitionResult.topLevelSuccessRef - } - } - } - }; + "200": { + "description": "successful operation", + "schema": { + "type": verbDefinitionResult.topLevelSuccessRefType, + "items": { + "$ref": "#/definitions/" + verbDefinitionResult.topLevelSuccessRef + } + } + } + }; }; return pathItemObject; } @@ -271,22 +309,32 @@ function createPathParameters(verbs, pathKeys) { pathKeys = pathKeys || []; var pathItemObject = []; - if (verbs.parameter && verbs.parameter.fields.Parameter) { - for (var i = 0; i < verbs.parameter.fields.Parameter.length; i++) { - var param = verbs.parameter.fields.Parameter[i]; - var field = param.field; - var type = param.type; - pathItemObject.push({ - name: field, - in: type === "file" ? "formData" : "path", - required: !param.optional, - type: param.type.toLowerCase(), - description: removeTags(param.description) - }); + if (!_.has(verbs, 'parameter.fields')) { + return pathItemObject; + } + var parametersTypes = _.get(verbs, 'parameter.fields'); + + for (var parameterType in parametersTypes) { + if ( + !parametersTypes.hasOwnProperty(parameterType) + || ['Path parameters', 'Query parameters'].indexOf(parameterType) === -1 + ) { + continue; } + + parametersTypes[parameterType].forEach(parameter => { + pathItemObject.push({ + name: parameter.field, + in: parameterType === "Path parameters" ? "path" : "query", + required: !parameter.optional, + type: parameter.type.toLowerCase(), + description: removeTags(parameter.description) + }); + }); } + return pathItemObject; }