My API documentation is getting quite large and I was wondering if it was possible to separate the openapi.yml file into separately managed chunks rather than having it all in one and have reDoc (or some other tool) combine it and then generate the HTML site.
Redoc has its own tool for that "Redoc CLI" npm #redocly/cli
checkout their tutorial https://github.com/Redocly/openapi-starter
with this tool you can:
split your actual docs with one command
(to paths, components, parameters, schema)
redocly split openapi.yaml --outDir openapi
lint them (separated files or final one)
redocly lint openapi/openapi.yaml
preview (with hot reloading on change)
redocly preview-docs openapi/openapi.yaml
and merge them back when production ready
redocly bundle openapi/openapi.yaml -o openapi.yaml
and even more...
Related
I'm following the official guide for Parcel 2.
By default parcel takes your input files and dumps them all in the same output directory.
The vast majority of developers have specific directory layouts for our projects. So parcel must offer a way for its users to put files and directories where we want them to go.
But I can't documentation for configuring output file layout.
How do I control where output files are created? And how to rename them?
For example, if I'm working with projectroot/src/js/index.js, how can I output to projectroot/dist/js/bundle.js
GitHub supports asciidoc readme files, but it looks like "include" is not supported.
I want to use doctoolchain which can render and export to html and pdf (and maybe into other formats). This tool works great.
I could use raw.githack.com to show the generated html file from the GitHub repository.
But I think it would be a good idea to have the result also as one (1) readme.adoc file.
How to export into one (1) asciidoc file, which I could use as it is as readme file so that github will render it and show? Best would be to use doctoolchain, when this tool will render my documentation it could also generate the one-file-asciidoc-documentation.
I think internally asciidoctor collects and merge all these "include" files. So maybe this file is already available in any place? The doctoolchain build folder contains only the target files.
You are right there is a long dicussion why includeis not supported by github.
You can achieve your goal with doctoolChain and pandoc(https://pandoc.org/). Following steps are required:
configure your docDir/Config.groovy
inputFiles should have docbook defined
inputFiles = [[file: 'yourfile', formats['docbook']]]
run the doctoolchain task generateDocbook - it creates ???.xml file somewhere in docDir/build
generate from the generated docbook again an asciidoctor file - `pandoc <FILENAME_OF_GENERATED_DOCBOOK.XML> -f docbook -t asciidoctor -o <FILENAME_OF_ASCIIDOCTOR_WHICH_HAS_EVERYTHING>
make sure it runs automatically and you commit it regulary
now you are ready
This script can be used to resolve includes and to generate one (1) output file:
https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/scripts/asciidoc-coalescer.rb
some information about the script and possible next steps you can read here:
AsciiDoc Backend (AsciiDoc 2 AsciiDoc) for preprocessing
to use it, ruby and asciidoc must be installed:
asciidoctor.org/#installation
I've defined my services API using OpenAPI3 and am using GitHub for linting with Spectral by running the following script:
spectral lint ./api/**/*.{json,yml,yaml} --verbose
Later on, I've noticed that many of the objects are shared within my definitions and instead of duplicating them I've decided to create shared definition files that I could reference later on.
Everything is working great, besides the fact that at the moment the shared files are just regular YML files and not OpenAPI definitions. That means that there is no linting for those files. When I've tried to make those files an OpenAPI definition I had to add the paths definition (and others) which are not required in my shared files.
What is the best way to create a shared library in OpenAPI which could also be linted?
Something similar to what I've done you can find in the following link
I use broccoli-less in my ember cli project and would like to use an addon (ember-cli-materialize), which uses broccoli-sass.
After installing the addon, i get: File to read not found or unreadable ../app.scss, because i also have an app.less file in my styles dir.
As i understand, this commit Allow multiple preprocessors per type should make it possible, although i might be missing something. Has anyone managed to use ember-cli with multiple preprocessors, and what changes is needed?
Ember-cli version: 1.13.1
Ember version: 1.12.0
Thanks
I know your circumstance is different than mine but this may help others or spur a better solution. I was added to a dev team to polish up an app already styled using LESS. I favor SASS and tried to use ember-cli-sass alongside ember-cli-less without any success.
You may want to look further into Ember-Cli's add.import
By adding your input configurations to ember-cli-build.js with the above, you can leverage either your bower-components directory (if used) or vendor directory, to import a compiled CSS doc (from Sass source files) that will build alongside the project quite nicely with a simple sass --watch <input:output> command.
The LESS files are ultimately compiled to app.css, and your SASS files to vendor.css (make sure you link to the stylesheet in your index page/template).
I'm trying to get some options out of a separate config.coffee into my main app.coffee. The way I try doesn't work somehow, I'm only getting:
ReferenceError: Can't find variable: require
Here are my two files, I really hope you can help me out here.
# app.coffee
config = require './config.coffee'
console.log config.api_key
# config.coffee
exports.config =
api_key: 'MY_SECRET_API_KEY'
oh, I thought if I require another file and compile my app.coffee it gets included.. is there a way to do this or do I have to put everything in one file?
You might want to edit your question to specify this.
There are some projects that let you "require" files and introduce a build step to concatenate and minify them into a single one. Not all of them follow the Common/JS module spec. You can also use AMD based tools to load files asynchronously.
Sprockets
Which uses comments like #= require jquery to require other files and then compiles them into a single file. While it's aimed at Rack based apps, it has a command line tool which you can use to automate the process.
url: https://github.com/sstephenson/sprockets
Snockets
This is based on Sprockets, but it runs on Node.js
url: https://github.com/TrevorBurnham/snockets
Browserify
This is another Node.js based tool.
Make node-style require() work in the browser with a server-side build step, as if by magic!
https://github.com/substack/node-browserify
Require.JS
This is AMD based, so it can load files asynchronously, but it also has an optimizer wich can concatenate files.
I'm sure there are many more. Each have their own way of doing things and you can make them work with CoffeeScript.