readmeio / github-readme-sync Goto Github PK

View Code? Open in Web Editor NEW

19.0 19.0 16.0 16.93 MB

GitHub Action for Automatically Syncing API Spec Files to ReadMe! [DEPRECATED]

Home Page: https://docs.readme.com/docs/automatically-sync-api-specification-with-github

JavaScript 100.00%

openapi swagger

github-readme-sync's People

Contributors

Stargazers

Watchers

Forkers

glarefurs1986 dschultzcontractor mdoyleaz oforce gkoberger rambocacing666 kedington koxa-io inaitech sofianegargouri

github-readme-sync's Issues

Send errors to ReadMe

It would be nice if all errors were surfaced to ReadMe (and email), since most people don't know to check the Actions tab. (A wrapper around setFailure would be nice?)

We should surface the errors right away in ReadMe if they pop up in the modal, AND we should make sure it shows up in the log!

I assume this is a limitation of the API, but it's not possible to create a new version on upload. For example, I am trying to follow an automated calver upload on a push to a branch. Here's a sample of what I'm doing for reproducibility:

name: Sync OAS to ReadMe
on:
  push:
    branches:
      - master
      - main
jobs:
  document:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: setup Node.js
        uses: actions/[email protected]
        with:
          node-version: "14.x"
      - name: install dependencies
        run: npm i swagger-inline
      - name: set version by calver
        id: ver
        run: |
          echo ::set-output name=VERSION::$(date +"%Y.%m.%d")
      - name: generate documentation
        run: npx swagger-inline */*.js --base baseSwagger.yaml --scope public > swagger.yaml
      - uses: readmeio/github-readme-sync@v2
        with:
          readme-oas-key: qTDbntRax07zYdWpdXUaaBhQePkZK2wO:5f97763f7abfc702cf63d010
          api-version: ${{steps.ver.outputs.VERSION}}
          oas-file-path: swagger.yaml

So I'm dynamically setting the api-version based on the output of date which will be format YYYY-MM-DD. However, this fails as the version does not already exist on readme.io.

Further, I've tried using yq to set the value directly in the OAS, but that similarly fails. I think, at the least, it should be documented that the specified api-version must already exist before upload.

An example of the yq command:

yq w -i baseSwagger.yaml info.version $(date +"%Y.%m.%d")

publish Guides

I'm wondering if this is the right tool for this job, but would be interesting if besides API reference,
we could also sync markdown files in the github repo with the "Guides" in our readmeio.
Is this something you would consider for this tool?

Better finding of oas file

Right now it only works if your file is called oas.yaml or something similar; we should search for it!

OpenAPI definition with references to external models

Hi All,

If i select to upload an OpenAPI definition which has references to models residing in another folder in the repo i get the following error during action execution:

Error: Error bundling your file: Error opening file "/home/runner/work/readmecom-trial/readmecom-trial/models/Pet.v1.yaml" 
ENOENT: no such file or directory, open '/home/runner/work/readmecom-trial/readmecom-trial/models/Pet.v1.yaml'

A sample method definition is looking like this:

paths:
  /pet:
    put:
      tags:
        - pet
      summary: Update an existing pet
      operationId: updatePet
      requestBody:
        description: Pet object that needs to be added to the store
        content:
          application/json:
            schema:
              $ref: ./models/Pet.v1.yaml
          application/xml:
            schema:
              $ref: ./models/Pet.v1.yaml
        required: true

My github action setup is like this:

name: Sync OAS to ReadMe
on:
  push:
    branches:
      - master
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: readmeio/github-readme-sync@v2
        with:
          readme-oas-key: XXXX           
          oas-file-path: './api/petclinic.yaml'
          api-version: 'v1.0.0'

Nothing too fancy there. I tried searching around for other options but found nothing.
Is there a way i can get this to work with the github action?

Unhandled promise rejection, [email protected]

Run readmeio/[email protected]
(node:2496) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'substr' of undefined
    at sanitize (/home/runner/work/_actions/readmeio/github-readme-sync/2.1.0/main.js:12:16)
    at sanitizeKeys (/home/runner/work/_actions/readmeio/github-readme-sync/2.1.0/main.js:36:29)
    at debug (/home/runner/work/_actions/readmeio/github-readme-sync/2.1.0/main.js:43:28)
    at run (/home/runner/work/_actions/readmeio/github-readme-sync/2.1.0/main.js:52:3)
    at Object.<anonymous> (/home/runner/work/_actions/readmeio/github-readme-sync/2.1.0/main.js:174:1)
    at Module._compile (internal/modules/cjs/loader.js:959:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:995:10)
    at Module.load (internal/modules/cjs/loader.js:815:32)
    at Function.Module._load (internal/modules/cjs/loader.js:727:14)
    at Function.Module.runMain (internal/modules/cjs/loader.js:1047:10)
    at internal/main/run_main_module.js:17:11
(node:2496) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
(node:2496) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

name: Sync to ReadMe
on:
  push:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@master
      - uses: readmeio/[email protected]
        with:
          readme-oas-key: ${{ secrets.*** }}

After update from 2.0 which had bugs, different bug is show.

Cast to ObjectId failed for value":oid:"

Run readmeio/[email protected] ##[error]500 - "{"error":"Cast to ObjectId failed for value \":oid:\" at path \"_id\" for model \"APISetting\""}"
Looks like something went wrong , just copy paste github actions from doc , and it fails

Show more info in ReadMe

This isn't meant for this repo, but I wanted to keep everything in one place. We add the repo name and other info to the oas file when we upload it; it'd be great to surface it and link to the repo/action/etc from the ReadMe dashboard:

Sync action silently fails with a TypeError & UnhandledPromiseRejectionWarning

The action appears to succeed with a green check, but if you examine the output it is failing with a TypeError.

Run readmeio/[email protected]
(node:2493) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'match' of undefined
    at /home/runner/work/_actions/readmeio/github-readme-sync/2.0.0/main.js:95:28
    at processTicksAndRejections (internal/process/task_queues.js:93:5)
(node:2493) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
(node:2493) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

This was is the relevant section of the action config:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@master
      - uses: readmeio/[email protected]
        with:
          readme-oas-key: xxxx
           
          # OPTIONAL CONFIG, use if necessary
          oas-file-path: './dev-ops-api/api/swagger.yaml'
          # api-version: 'v1.0.0'

Only upload on change

We should do a hash of the swagger file, and only upload if it's changed! Otherwise we're gonna end up messing up some stuff at some point... we don't want to be doing this every time someone pushes; we'll end up overwriting data or other weird stuff.

contributing.md

gpnpm login --registry=https://npm.pkg.github.com/
20200415_1.txt
#10 #9 #3 #4 #7

readmeio / github-readme-sync Goto Github PK

github-readme-sync's People

Contributors

Stargazers

Watchers

Forkers

github-readme-sync's Issues

Recommend Projects

Recommend Topics

Recommend Org

Jobs