syroegkin / swagger-markdown Goto Github PK

View Code? Open in Web Editor NEW

231.0 231.0 86.0 2.89 MB

swagger to markdown transpiler

License: MIT License

JavaScript 3.54% Shell 0.19% TypeScript 96.27%

javascript js markdown node nodejs openapi swagger

swagger-markdown's People

Contributors

Stargazers

Watchers

swagger-markdown's Issues

Converting yml to markdown is not escaping "|" (pipe) characters

Example of .yml file section:

expiration_date:
  type: string
  description: "Timestamp in YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM|-HH:MM|Z] format"

Pipes aren't escaped so that after converting to markdown the table isn't correctly formatted.

Allow to select atx or setext headers style

Or just remove unnecessary triple hashes in each header

TypeError: content.trimEnd is not a function

TypeError: content.trimEnd is not a function
    at handleRunEnd (/home/hughes/.nvm/versions/node/v8.16.2/lib/node_modules/swagger-markdown/node_modules/markdownlint/lib/md037.js:38:27)
    at MD037.forEachLine (/home/hughes/.nvm/versions/node/v8.16.2/lib/node_modules/swagger-markdown/node_modules/markdownlint/lib/md037.js:142:13)
    at forMetadata (/home/hughes/.nvm/versions/node/v8.16.2/lib/node_modules/swagger-markdown/node_modules/markdownlint/helpers/helpers.js:259:5)
    at Array.forEach (<anonymous>)
    at forEachLine (/home/hughes/.nvm/versions/node/v8.16.2/lib/node_modules/swagger-markdown/node_modules/markdownlint/helpers/helpers.js:257:16)
    at Object.MD037 [as function] (/home/hughes/.nvm/versions/node/v8.16.2/lib/node_modules/swagger-markdown/node_modules/markdownlint/lib/md037.js:71:5)
    at forRule (/home/hughes/.nvm/versions/node/v8.16.2/lib/node_modules/swagger-markdown/node_modules/markdownlint/lib/markdownlint.js:593:20)
    at Array.forEach (<anonymous>)
    at lintContent (/home/hughes/.nvm/versions/node/v8.16.2/lib/node_modules/swagger-markdown/node_modules/markdownlint/lib/markdownlint.js:639:14)
    at lintNextItem (/home/hughes/.nvm/versions/node/v8.16.2/lib/node_modules/swagger-markdown/node_modules/markdownlint/lib/markdownlint.js:746:9)

[help] can swagger-markdown support to export js schema to markdown?

I use fasitfy.
There are fastify-swagger.
So i can just write schema(which is js-file) to create the api documentation.

But how can i export it to a markdown file.

It seems that swagger-markdown can export yaml file to markdown file.

JSON issue

error Error parsing JSON at "/home/work/..../package.json", "/.../package.json: Unexpected string in JSON at position 498".

Error: Error resolving $ref pointer

The script fails to render markdown when a $ref pointer points to a file that's inside a subdirectory.

It works well if the file resides in the same directory.

A project with the following structure will fail.
--docs
----schemas
------type1.yaml
------type2.yaml
----api.yaml (has $refs to type1 and type2)

Doesn't support complex models

For example I have parameter with schema.

                    {
                        "name": "paymentRequest",
                        "in": "body",
                        "description": "",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/PaymentRequest"
                        }
                    }

And it's definition in swagger file:

        "PaymentRequest": {
            "type": "object",
            "properties": {
                "CreatedDate": {
                    "format": "date-time",
                    "type": "string"
                },
                "IsAsync": {
                    "type": "boolean"
                },

But this information doesn't passing to method description

Edit templates to translate custom fields?

Hello Sergii: Thank you for this script! It works just as described, and yields nice results.

We're now trying to modify the script's templates, to extract and output (with different column headings) some custom fields from our swagger. Would this be as straightforward as editing the parameters.js file, writing the edited copy back to our local installation's package.tgz archive, and re-running the script?

Or would we need to clone your repo, edit unarchived files, and recompile? Double thanks for any guidance about how to customize the runtime behavior.

[TypeError: Cannot convert undefined or null to object]

Every time i want to convert my generated .yaml or .json file i get this error.

[TypeError: Cannot convert undefined or null to object]

My file works with swagger ui and has just some warnings.

Link to my file: https://drive.google.com/open?id=0Bz6uStaBekRTOXYydVdTajlwNk0

Anchor links do not work

Generated anchor links contains dots "." and does not work. By github documentation dots should be replaced to empty string ''

RangeError: Maximum call stack size exceeded

 swagger-markdown -i ./openapi.yaml
RangeError: Maximum call stack size exceeded
    at Url.parse (node:url:170:37)
    at urlParse (node:url:158:13)
    at Object.urlResolve [as resolve] (node:url:674:10)
    at $Refs._resolve (/usr/local/lib/node_modules/swagger-markdown/node_modules/@apidevtools/json-schema-ref-parser/lib/refs.js:147:21)
    at $Refs.get (/usr/local/lib/node_modules/swagger-markdown/node_modules/@apidevtools/json-schema-ref-parser/lib/refs.js:98:15)
    at partiallyDereference (/usr/local/lib/node_modules/swagger-markdown/bin/convert.js:44:43)
    at partiallyDereference (/usr/local/lib/node_modules/swagger-markdown/bin/convert.js:46:20)
    at partiallyDereference (/usr/local/lib/node_modules/swagger-markdown/bin/convert.js:46:20)
    at partiallyDereference (/usr/local/lib/node_modules/swagger-markdown/bin/convert.js:46:20)
    at partiallyDereference (/usr/local/lib/node_modules/swagger-markdown/bin/convert.js:44:16)

on around 800 lines of yaml.

Reference only parameters are ignored.

This is valid swagger 2.0, but parameters specified this way are ignored.

/{clientId}:
get:
description: |
Get the client.
parameters:
- $ref: '#/definitions/clientId'

There is no error when the file is processed, but the Name, Located in, and Description columns in the generated parameters table are blank.

Andy

Add support for Tags and Tag Grouping of Paths?

Swagger supports grouping paths via tags https://swagger.io/docs/specification/grouping-operations-with-tags/.

This request is to ask for support for add tag groups as markdown header groupings.

An example output would be something like:

# My Awesome API
## Version 2.0
### Security
security stuff...


### Dogs
These endpoints are dog related endpoints.

#### /list
##### Get
###### Summary
Get all available dogs
###### Description
We'll give a list of all the dogs in the world, paged of course

### Cats
These endpoints are cats related endpoints.

#### /list
##### Get
###### Summary
Get all available cats
###### Description
We'll give a list of all the cats in the world, paged of course

This proposed solution would require that:

Swagger paths will need to be grouped by tags (adding 1 layer of nesting)
When there's no tag grouping, do current behavior (aka, no nesting)

Does not support int8 type

Is your feature request related to a problem? Please describe.

{
  stack: 'MissingPointerError: Token "int8" does not exist.\n' +
    '    at Pointer.resolve (/opt/homebrew/lib/node_modules/swagger-markdown/node_modules/@apidevtools/json-schema-ref-parser/lib/pointer.js:94:13)\n' +
    '    at $Ref.resolve (/opt/homebrew/lib/node_modules/swagger-markdown/node_modules/@apidevtools/json-schema-ref-parser/lib/ref.js:115:20)\n' +
    '    at $Refs._resolve (/opt/homebrew/lib/node_modules/swagger-markdown/node_modules/@apidevtools/json-schema-ref-parser/lib/refs.js:156:15)\n' +
    '    at inventory$Ref (/opt/homebrew/lib/node_modules/swagger-markdown/node_modules/@apidevtools/json-schema-ref-parser/lib/bundle.js:99:23)\n' +
    '    at crawl (/opt/homebrew/lib/node_modules/swagger-markdown/node_modules/@apidevtools/json-schema-ref-parser/lib/bundle.js:74:11)\n' +
    '    at crawl (/opt/homebrew/lib/node_modules/swagger-markdown/node_modules/@apidevtools/json-schema-ref-parser/lib/bundle.js:77:11)\n' +
    '    at crawl (/opt/homebrew/lib/node_modules/swagger-markdown/node_modules/@apidevtools/json-schema-ref-parser/lib/bundle.js:77:11)\n' +
    '    at crawl (/opt/homebrew/lib/node_modules/swagger-markdown/node_modules/@apidevtools/json-schema-ref-parser/lib/bundle.js:77:11)\n' +
    '    at bundle (/opt/homebrew/lib/node_modules/swagger-markdown/node_modules/@apidevtools/json-schema-ref-parser/lib/bundle.js:22:3)\n' +
    '    at SwaggerParser.bundle (/opt/homebrew/lib/node_modules/swagger-markdown/node_modules/@apidevtools/json-schema-ref-parser/lib/index.js:228:5)',
  code: 'EMISSINGPOINTER',
  message: 'Token "int8" does not exist.',

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered

Additional context

SecurityDefinitions...replace is not a function

I receive the following error when trying to use your lib on yaml downloaded from the swagger site.

 swagger-markdown -i swagger.yaml

TypeError: securityDefinitions[type][value].replace is not a function
    at /Users/al/.nvm/versions/node/v6.11.1/lib/node_modules/swagger-markdown/bin/transformers/securityDefinitions.js:31:86
    at Array.map (native)
    at /Users/al/.nvm/versions/node/v6.11.1/lib/node_modules/swagger-markdown/bin/transformers/securityDefinitions.js:24:44
    at Array.map (native)
    at module.exports (/Users/al/.nvm/versions/node/v6.11.1/lib/node_modules/swagger-markdown/bin/transformers/securityDefinitions.js:20:36)
    at Object.<anonymous> (/Users/al/.nvm/versions/node/v6.11.1/lib/node_modules/swagger-markdown/bin/index.js:57:21)
    at Module._compile (module.js:570:32)
    at Object.Module._extensions..js (module.js:579:10)
    at Module.load (module.js:487:32)
    at tryModuleLoad (module.js:446:12)

markdownlint.json issue

I am using swagger-merger, which use swagger-markdown

With the new latest version (1.4.5) I have an issue:

yarn global add swagger-merger
npx swagger-markdown -i bundle.yaml -o README.md
...
npm WARN exec The following package was not found and will be installed: swagger-markdown

internal/modules/cjs/loader.js:818

  throw err;

  ^



Error: Cannot find module '../.markdownlint.json'

Require stack:

- /home/golang/.npm/_npx/529cdd1e3bb539d4/node_modules/swagger-markdown/bin/convert.js

- /home/golang/.npm/_npx/529cdd1e3bb539d4/node_modules/swagger-markdown/bin/index.js

    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:815:15)

    at Function.Module._load (internal/modules/cjs/loader.js:667:27)

    at Module.require (internal/modules/cjs/loader.js:887:19)

    at require (internal/modules/cjs/helpers.js:74:18)

    at Object.<anonymous> (/home/golang/.npm/_npx/529cdd1e3bb539d4/node_modules/swagger-markdown/bin/convert.js:17:26)

    at Module._compile (internal/modules/cjs/loader.js:999:30)

    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1027:10)

    at Module.load (internal/modules/cjs/loader.js:863:32)

    at Function.Module._load (internal/modules/cjs/loader.js:708:14)

    at Module.require (internal/modules/cjs/loader.js:887:19) {

  code: 'MODULE_NOT_FOUND',

  requireStack: [

    '/home/golang/.npm/_npx/529cdd1e3bb539d4/node_modules/swagger-markdown/bin/convert.js',

    '/home/golang/.npm/_npx/529cdd1e3bb539d4/node_modules/swagger-markdown/bin/index.js'

  ]

}

Not showing definitions

When I convert my swagger.yaml to markdown, it doesn't convert my definitions. It shows the info section and the paths sections great but not the "definitions".

TOC support

Hi,

can you add TOC generating support with path depth control, please? So this is not issue but feature request.

Btw. good job and thank you for this very usefull npm package 👍.

Error: "Cannot read properties of null (reading 'get')"

Today, I wanted to update my API docs of one of my projects. I am using swaggo/swag to generate the swagger API definition and then generating a markdown file using swagger-markdown.

But when executing swagger-markdown on the generated definition, I get the following exception.

TypeError: Cannot read properties of null (reading 'get')
    at /usr/lib/node_modules/swagger-markdown/dist/lib/markdown/markdown.js:24:77
    at Array.map (<anonymous>)
    at Markdown.line (/usr/lib/node_modules/swagger-markdown/dist/lib/markdown/markdown.js:24:35)
    at transformInfo (/usr/lib/node_modules/swagger-markdown/dist/transformers/info.js:32:16)
    at transformSwaggerV2 (/usr/lib/node_modules/swagger-markdown/dist/transformers/documentV2.js:17:42)
    at transfromSwagger (/usr/lib/node_modules/swagger-markdown/dist/index.js:67:61)
    at /usr/lib/node_modules/swagger-markdown/dist/index.js:102:26
    at Generator.next (<anonymous>)
    at fulfilled (/usr/lib/node_modules/swagger-markdown/dist/index.js:5:58)

Here you can find the used swagger.json file that causes the issue.
https://github.com/zekroTJA/shinpuru/blob/dbd594a088840ec24086f9b2a7d5728676b8c8b9/docs/restapi/v1/swagger.json

get rid of html tags

get rid of html tags so it will be displayed properly with bitbucket

Swagger Markdown Web UI

I've created a quick (hacky) web UI for swagger-markdown for convenience, and it's currently deployed here (repo here).

Couldn't find @syroegkin's email in his profile, so asking for permission for it to be left up here :)

Add support for path response root level $ref

Currently Swagger 2.0 supports the following:

paths:
  /user
    get:
      ...
    responses:
      200:
        description: "successful operation"
        schema:
          $ref: '#/definitions/User'
      400:
        $ref: '#/responses/BadRequest'
responses:
  BadRequest:
    description: Bad request
    schema:
      $ref: "#/definitions/ErrorResponse"
definitions:
  ErrorResponse:
    required:
      - message
    properties:
      message:
        type: string

This will fail when trying to process the content under 400, first because pathResponses.js assumes that at least a description will be provided, this can be easily fixed adding an if statement, but then some logic needs to be added to identify if a $ref is present and process the reference so the content is properly printed or at least linked.

overwrites input file if not yaml

I've got my api defined as json api.json. When I run;

swagger-markdown -i api.json

It overwrites api.json with markdown content. Oddly enough the yaml loader deals with json without issue.

Body request (requestBody) is not displayed

I have my YAML file with request and their requestBody, but when i convert to markdown, request body is not displayed, could you help me, thanks.

Properties in response not shown when schema type is "object" having one array property

swagger-markdown version 1.2.0

Input

---
  swagger: "2.0"
  host: "0.0.0.0:11116"
  basePath: "/"
  schemes: 
    - "http"
  info: 
    title: "REST API"
    version: "1"
  tags: []
  paths: 
    /v1/notifications/account/{accountId}: 
      get: 
        summary: "Retrieves all notifications for given accountId."
        operationId: "getV1NotificationsAccountAccountid"
        parameters: 
          - 
            type: "integer"
            name: "accountId"
            in: "path"
            required: true
          - 
            type: "array"
            description: "Optional properties to filter by. Can be multiple."
            x-constraint: 
              single: true
            items: 
              type: "string"
              enum: 
                - "read"
                - "completed"
            collectionFormat: "multi"
            name: "skip"
            in: "query"
            required: false
        tags: 
          - "v1"
        responses: 
          200: 
            schema: 
              type: "object"
              properties: 
                data: 
                  type: "array"
                  items: 
                    type: "object"
                    properties: 
                      notificationId: 
                        type: "integer"
                        description: "ID of the notification"
            description: "Successful"

Output

Notice for the Responses, the Schema column says only 'object' instead of saying it's an array of integers.

#  REST API
## Version: 1

### /v1/notifications/account/{accountId}

#### GET
##### Summary:

Retrieves all notifications for given accountId.

##### Parameters

| Name | Located in | Description | Required | Schema |
| ---- | ---------- | ----------- | -------- | ---- |
| accountId | path |  | Yes | integer |
| skip | query | Optional properties to filter by. Can be multiple. | No | [ string ] |

##### Responses

| Code | Description | Schema |
| ---- | ----------- | ------ |
| 200 | Successful | object |

syroegkin / swagger-markdown Goto Github PK

swagger-markdown's People

Contributors

Stargazers

Watchers

Forkers

swagger-markdown's Issues

Additional context

Recommend Projects

Recommend Topics

Recommend Org