search

fsbahman / apidoc-swagger

apidoc and swagger are two nice projects which are focusing on documentation of APIs. This project is a middle tier which tries to bring them together in a sense that it uses apidoc to convert inline documentation to json schema and later convert it to swagger json schmea.
Other
251 stars 129 forks source link

apidoc-swagger needs to be updated to run with Node.js 12 #40

Open datdinhquoc opened 5 years ago

datdinhquoc commented 5 years ago

apidoc-swagger doesn't run on Node.js 12 any more, it complains something about 'primordials':

fs.js:27
const { Math, Object } = primordials;
                         ^

ReferenceError: primordials is not defined
    at fs.js:27:26
    at req_ (/home/abix/.nvm/versions/node/v12.2.0/lib/node_modules/apidoc-swagger/node_modules/natives/index.js:143:24)
    at Object.req [as require] (/home/abix/.nvm/versions/node/v12.2.0/lib/node_modules/apidoc-swagger/node_modules/natives/index.js:55:10)
    at Object. (/home/abix/.nvm/versions/node/v12.2.0/lib/node_modules/apidoc-swagger/node_modules/graceful-fs/fs.js:1:37)
    at Module._compile (internal/modules/cjs/loader.js:759:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:770:10)
    at Module.load (internal/modules/cjs/loader.js:628:32)
    at Function.Module._load (internal/modules/cjs/loader.js:555:12)
    at Module.require (internal/modules/cjs/loader.js:666:19)
    at require (internal/modules/cjs/helpers.js:16:16)
rusekr commented 5 years ago

I'am got this error too

rusekr commented 5 years ago

i've tried to replace dependency of fs-extra with latest and error gone but result swagger.json became corrupt.

fsbahman commented 5 years ago

I've attempted before to update dependencies with recent versions, it was more work than expected, I need to find a time to fix it, if anyone could help will be nice.

SaudTauqeer commented 4 years ago

I can try to help with it. Any pointers for getting started?

learningfun-dev commented 4 years ago

@fsbahman Fixed this issue, can you please take a look at the PR https://github.com/fsbahman/apidoc-swagger/pull/49

fsbahman commented 4 years ago

Thanks @kalramanoj2002 I will have a look.

fsbahman commented 4 years ago

New version v0.3.1 is released thanks to @kalramanoj2002, please check it out if issues are solved.

rusekr commented 4 years ago

have 1 error with 0.3.1: using old stable config (apidoc.json in root of project):

{
  "_comment": "REST API version",
  "version": "1.0.0",
  "sampleUrl": false,
  "title": "REST documentation",
  "header": {
    "title": "",
    "filename": "src/apidoc/header.md"
  },
  "footer": {
    "title": "",
    "filename": "src/apidoc/footer.md"
  }
}

Using this command in root of project:

npx apidoc-swagger -i src/rest/ -o built/public/doc-rest

Getting this error:

error: Can not read: src/apidoc/header.md.

Tried to use absulute path to file with no success. File exists and apidoc itself sees and uses it.

learningfun-dev commented 4 years ago

@fsbahman @rusekr Fixed the header/footer issue. Can you please take a look https://github.com/fsbahman/apidoc-swagger/pull/51

rusekr commented 4 years ago

@fsbahman @rusekr Fixed the header/footer issue. Can you please take a look

51

Tested. Now error about header gone, but got new error:

# npx apidoc-swagger -i src/rest/ -o built/public/doc-rest
error: Empty parser result. 
{
  File: 'src/rest/project.js',
  Block: 1,
  Element: '@apiDescription',
  Source: '@apiDescription '
}

Where in project.js apiDescription is just empty:

  /**
   * @apiVersion 1.0.0
   * @apiPermission project.settings.get
   * @api {get} /project/settings Get project settings list
   * @apiDescription 
   * @apiName GetProjectSettings
   * @apiGroup ProjectSettings

Filled description and now it generates file without errors. Thanks!

learningfun-dev commented 4 years ago

@rusekr @fsbahman is apiDescription an optional field? do we needs to handle the above scenario i.e. it should not throw error if apiDescription is empty or not provided?

fsbahman commented 4 years ago

I will spend some time later this week to see what is wrong, maybe PR from @rusekr is good enough, I have to extent the unit test to find this issues as well. Also after upgrading some of the dependencies in this PR build is failing on CircleCi, look like some of the packages are not Linux compatible.

rusekr commented 4 years ago

Vote for 0.3.2 patch with patched headers. It can be used now with node 12 at all. Error with description is very minor for me. :)

fsbahman commented 4 years ago

Ok so for now I will just merge it and release new version. Thanks!

fsbahman commented 4 years ago

Done! v0.3.2