readmeio / github-readme-sync Goto Github PK
View Code? Open in Web Editor NEWGitHub Action for Automatically Syncing API Spec Files to ReadMe! [DEPRECATED]
Home Page: https://docs.readme.com/docs/automatically-sync-api-specification-with-github
GitHub Action for Automatically Syncing API Spec Files to ReadMe! [DEPRECATED]
Home Page: https://docs.readme.com/docs/automatically-sync-api-specification-with-github
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")
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?
Right now it only works if your file is called oas.yaml
or something similar; we should search for it!
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?
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.
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
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'
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.