For some REST APIs written in PHP, I was asked to create Swagger documentation, and since I was not aware of any easy way of annotating those existing APIs and create such a documentation, I used this editor to generate some for now.
I saved the JSON and YAML files created using that editor, and now I need to create the "interactive" Swagger documentation from there.
Can someone please let me know how I can convert the Swagger JSON specification file to an actual Swagger documentation?
I am on the Windows platform and do not know anything about Ant/Maven.
Try to use redoc-cli.
I was using bootprint-openapi by which I was generating a bunch of files (bundle.js, bundle.js.map, index.html, main.css and main.css.map) and then you can convert it into a single .html file using html-inline to generate a simple index.html file.
Then I found redoc-cli very easy to to use and output is really-2 awesome, a single and beautiful index.html file.
Installation:
npm install -g redoc-cli
Usage:
redoc-cli bundle -o index.html swagger.json
I was not satisfied with swagger-codegen when I was looking for a tool to do this, so I wrote my own. Have a look at bootprint-swagger
The main goal compared to swagger-codegen is to provide an easy setup (though you'll need nodejs).
And it should be easy to adapt styling and templates to your own needs, which is a core functionality of the bootprint-project
Everything was too difficult or badly documented so I solved this with a simple script swagger-yaml-to-html.py, which works like this
python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html
This is for YAML but modifying it to work with JSON is also trivial.
I spent a lot of time and tried a lot of different solutions - in the end I did it this way :
<html>
<head>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist#3.17.0/swagger-ui.css">
<script src="//unpkg.com/swagger-ui-dist#3/swagger-ui-bundle.js"></script>
<script>
function render() {
var ui = SwaggerUIBundle({
url: `path/to/my/swagger.yaml`,
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
]
});
}
</script>
</head>
<body onload="render()">
<div id="swagger-ui"></div>
</body>
</html>
You just need to have path/to/my/swagger.yaml served from the same location.
(or use CORS headers)
Check out pretty-swag
It has
Similar looking as Swagger-Editor's right panel
Search / Filter
Schema Folding
Live Feedback
Output as a single html file
I was looking at Swagger Editor and thought it could export the preview pane but turned out it cannot. So I wrote my own version of it.
Full Disclosure: I am the author of the tool.
See the swagger-api/swagger-codegen project on GitHub ; the project README shows how to use it to generate static HTML. See Generating static html api documentation.
If you want to view the swagger.json you can install the Swagger UI and run it. You just deploy it on a web server (the dist folder after you clone the repo from GitHub) and view the Swagger UI in your browser. It's a JavaScript app.
You can also download swagger ui from: https://github.com/swagger-api/swagger-ui,
take the dist folder, modify index.html:
change the constructor
const ui = SwaggerUIBundle({
url: ...,
into
const ui = SwaggerUIBundle({
spec: YOUR_JSON,
now the dist folder contains all what you need and can be distributed as is
For Swagger API 3.0, generating Html2 client code from online Swagger Editor works great for me!
Give a look at this link : http://zircote.com/swagger-php/installation.html
Download phar file https://github.com/zircote/swagger-php/blob/master/swagger.phar
Install Composer https://getcomposer.org/download/
Make composer.json
Clone swagger-php/library
Clone swagger-ui/library
Make Resource and Model php classes for the API
Execute the PHP file to generate the json
Give path of json in api-doc.json
Give path of api-doc.json in index.php inside swagger-ui dist folder
If you need another help please feel free to ask.
There's a small Java program which generates docs (adoc or md) from a yaml file.
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withSwaggerMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.DE)
.build();
Swagger2MarkupConverter builder = Swagger2MarkupConverter.from(yamlFileAsString).withConfig(config).build();
return builder.toFileWithoutExtension(outFile);
Unfortunately it only supports OpenAPI 2.0 but not OpenAPI 3.0.
If you commit your JSON file in Gitlab, it will render it for you.
Redocly's CLI interface has a tool to build HTML docs from OpenAPI spec files.
sudo npm i -g #redocly/cli
redocly build-docs my-swagger.yml -o docs.html
Related
I have written the logic for a backend e-commerce REST API, and I have documented it here:
https://app.swaggerhub.com/apis-docs/chris-larham-1983/e-Commerce_Registration_Customers_Addresses_Orders/0.1#/. I would like to include this specification in my project that is deployed on Heroku so that the project and documentation are in one place.
I have configured the Heroku database, populated the 'customers', 'orders', 'products', and 'addresses' table with sample data, and the specified endpoints are working as specified in the document - for example, https://codecademy-e-commerce-rest-api.herokuapp.com/api/products.
So far I have tried downloading the documentation from within my Swagger Hub account in 'html', 'html2', and 'dynamic html' formats, as I thought I would just include a .html document in my project. However, these downloaded documents do not closely resemble the documentation as linked above; the formatting is very different and does not look as professional.
Does anybody know I could include my Swagger Hub API definition in my project so that the documentation and project are both hosted on Heroku?
Thanks in advance for any help/pointers to tutorials.
After a couple of hours of searching and configuring, I have solved this problem thanks to an npm package called swagger-ui-express. This package can be found here: https://www.npmjs.com/package/swagger-ui-express.
I downloaded my API specification in the format JSON resolved and added it to my project as a file named swagger.json. Then I followed the configuration information in the swagger-ui-express documentation, uploaded to heroku, and it worked!
The lines of code I added in index.js were:
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
I hope this helps somebody in the future :)
From http://ember-cli.com/user-guide/:
Application configurations from your ember-cli-build.js file will be
stored inside a special meta tag in dist/index.html.
sample meta tag:
<meta name="user/config/environment" content="%7B%22modulePre.your.config">
This meta tag is required for your ember application to function
properly. If you prefer to have this tag be part of your compiled
javascript files instead, you may use the storeConfigInMeta flag in
ember-cli-build.js.
// ember-cli-build.js
var app = new EmberApp({
storeConfigInMeta: false
});
In production, this meta tag looks like
<meta name="app/config/environment" content="%7B%22modulePrefix%22%3A%app%22%2C%22environment%22%3A%22production%22%2C%22baseURL%22%3A%22/%22%2C%22locationType%22...
and is quite long. Wouldn't it be more performant to make the configuration object part of the Javascript asset, rather than requiring the app to parse all of that text after it boots?
By having it external to the JS payload, it's possible to change the meta tag to configure the JS app without having to recompile the app. It's quite useful in certain situations ...
A few years late to the party, but this GitHub comment from the original PR to add this config describes the original intent of the author.
Basically, having config in Index.html allows the JS artefacts under dist/ to be consistent across environments.
I am developing a simple CRM app using Laravel 5.2 and ReactJS. Previously I was using them independently, but now I want to try to combine them together so Laravel will be my API and front-end will be all in ReactJS.
As far as I know when my app is ready to go live I will serve my master view which includes root div, bundle.js etc.
When it comes to development part I am a little confused. I really love react hot reload, but for now I had to do a little walk around to make this works.
I run two servers side by side. Webpack-dev-server and homestead, so I am able to do calls to my API. But I also have to have additional index.html for webpack-dev-server. When i change something in my index.blade.php view I also need to change this in this index.html and this is a little bit of pain.
Is there any cool trick that I can apply to improve my workflow? If there is any example please provide me a link, because I wasn't able to find one. There are many small todo apps that doesn't really solve my problem.
PS. Currently I am using this approach https://github.com/sexyoung/laravel-react-webpack
#UPDATE
Well I think I have found an acceptable solution. I will stick with webpack server configuration that I have provided in my question (it is really great cause you can use hot reload + you api calls are redirected to backend port, so instead of localhost:8080/api/user... you call /api/user/1), but I have also developed a simple elixir extension that compiles php to simple static HTML page which solves the problem of editing two index files (we all know programmers are lazy).
var php2html = require("gulp-php2html");
var gulp = require("gulp");
var rename = require("gulp-rename");
var Task = elixir.Task;
elixir.extend("php2html", function (message) {
new Task("php2html", function () {
return gulp.src("./resources/views/index.blade.php")
.pipe(php2html())
.pipe(rename('index.html'))
.pipe(gulp.dest("./"));
})
.watch("resources/views/index.blade.php");
});
elixir(function (mix) {
mix.sass('app.scss');
mix.php2html();
});
So at the moment I have two index files:
index.blade.php in resources/views which is resolved by the router on production
index.html in root of my application folder which is used by webpack-dev-server for development
and of course now these files are sync cause of gulp watch :)
If there is any better approach let me know guys.
I have usually solved this problem (duplicated index.html/php file) using this webpack plugin: https://github.com/ampedandwired/html-webpack-plugin
The idea is the opposite of yours I think. Instead of compiling your php files into static html, you can use the HtmlWebpack plugin to output a index.tmpl.php file (or whatever extension you need) using the filename configuration option. Normally I set that path to be the templates folder of my application server.
I believe this approach is generally easier than doing the other way round.
Using this plugin has other benefits, such as automatic bundle script tags injection depending on your Webpack output config, and automatic cache-bursting file hash added to the script tag urls.
We decided to give it a spin and we started fresh project using Angular2. So far so good, but at this point we're facing an issue. At this point, what is the proper approach to i18n for Angular2? We've researched a little and found this:
https://github.com/angular/i18n
However last commit is more than 5 months old... Doesn't look like active development.
Anyone tried using angular-translate or angular-gettext? Or maybe with Angular2 it's better to wrap something JS like i18next? Anyone could share their thoughts? Maybe you faced the same problem?
Plunk was updated to Angular 2 Final: https://plnkr.co/edit/4euRQQ. Things seem to work the same as in RC7.
New i18n section has been added to Angular 2 official docs. Basically, it explains in details what happens in the plunkr above.
XLIFF is the only format for translations, no json support.
A translation source file (xliff, xlf) should be created using ng-xi18n tool:
package.json:
"scripts": {
"i18n": "ng-xi18n",
...
}
and
npm run i18n
See the Merge translation section for details about merging a translation into a component template. It's done using SystemJS Text plug-in.
Another example using Gulp http://www.savethecode.com/angular2-i18n-native-support/
Older staff:
Update based on RC7 and links provided by Herman Fransen:
I've made a minimal Plunkr example: https://plnkr.co/edit/4W3LqZYAJWdHjb4Q5EbM
Comments to plunkr:
bootstrap should provide TRANSLATIONS, TRANSLATIONS_FORMAT, LOCALE_ID with values -> setup translations
translatable items in html-templates should use directive i18n
translations are stored in .xlf file. Ties between languages is done through Id, ties with html by a value of <source> tag in xlf
currently xlf files are not used directly; a .ts file is manually created to wrap the content of xlf in an exportable variable. I guess, this should be working automagically in final release (maybe even now).
This is the first officially documented approach I found.
However, it's still barely usable. I see the following issues in the current implementation:
Language is set at bootstrap, unable to change it in run-time. This should be changed in Final.
Id of a translatable item in xlf is generated SHA. Current way to get this id is a bit messy: you create a new translatable item, use it, copy SHA id from error and paste into your i18n.lang.xlf file.
There is a big documentation pull request concerning i18n
Older staff:
Release notes https://github.com/angular/angular/blob/master/CHANGELOG.md have a record
i18n: merge translations 7a8ef1e
A big chunk of i18n was introduced in Angular 2 RC5
Unfortunately, still no documentation available.
Everyone's eager for the official implementation, but this one worked for my use case:
https://github.com/ocombe/ng2-translate
README is fairly thorough, and if you need something real particular (for me it was code-splitting) the code itself isn't too long or hard to read.
Support for i18n is now official in Angular 2 RC6
Official release blog:
https://angularjs.blogspot.nl/2016/09/angular-2-rc6_1.html
A sample of internationalization with Angular 2 RC6
https://github.com/StephenFluin/i18n-sample
More info how the new concept of i18n works in angular2:
https://lingohub.com/blog/2015/03/angular-2-i18n-update-ng-conf-2015
I found another way to implement this using pipe and service
HTML
<!-- should display 'hola mundo' when translate to Spanish -->
<p>{{ 'hello world' | translate }}</p>
TYPESCRIPT
...
// "this.translate" is our translate service
this.translate.use('es'); // use spanish
...
// should display 'hola mundo' when translated to Spanish
this.translatedText = this.translate.instant('hello world');
...
https://scotch.io/tutorials/simple-language-translation-in-angular-2-part-1
https://scotch.io/tutorials/simple-language-translation-in-angular-2-part-2
There is an official support for i18n in Angular.io here:
https://angular.io/docs/ts/latest/cookbook/i18n.html
But! As mentioned in docs:
You need to build and deploy a separate version of the application for
each supported language!
That makes this feature useless in most cases ...
Unless you will use it without CLI as described here:
https://devblog.dymel.pl/2016/11/03/angular2-and-i18n-translate-your-app/
I am putting together a POC and the official documentation is cumbersome to say the least, so I tried ngx-translate http://www.ngx-translate.com/ and I literally had the hello world working in a few minutes, there are few caveats:
I've read of people complaining about performance, because of the pipes, but reading the github issues, it seems that it is getting resolved
It is only for i18n or Translations it does not deal with i10n or Localization
There are few warning errors with Angular4 but it works anyways
long story short I liked ngx-translate if you have a small app and only need translation
I personally wanted Localization, so I am looking at
https://github.com/robisim74/angular-l10n
. It looks pretty good, but I haven't tested, so I'll let you know later, or you guys can go and we all try
We have an internal python API that we have documented using Sphinx. part of the system uses YAML for configuration files that contain reference to py file that use the API. I've been asked to see if there is a way, using sphinx, to link the YAML config files to the the appropriate API docs. I've been doing research on google, here and sphinx site and it looks like I may be able to use intersphinx but I'm unclear how to make the connection between the two.
so for example: here is the yaml config file:
HALT_LEVEL: Any
SUITE: "Checkin Tests"
DESCRIPTION: "checkin test suite"
TESTLIST:
- TESTCASE: install stuff
DESC: "Installs RPM"
TESTGROUP: sprint_0
TESTFILE: install_stuff.py # I would like to turn this into a link to our sphinx docs
# for this. This file is already part of sphinx docs"
So then when someone is looking at the html/sphinx version of the the above file they could click on install_stuff.py and it take them to the docs that exist
Is this possible?
thanks in advance,
Greg.
Just for those that may be interested. I was able to do this but not using Sphinx. I used pyyaml to read the file and pygments to generate the html then hacked the generated html.
Since pygments doesn't appear to allow live href links what to add them what I is
# create a yaml string using pyyaml and then modify the string.
href = '[ahref="%s"]%s[/a]' % (hrefData, hrefString)
yamldata['KEYWORD'][idx]['HOST'] = href
This changes the referenced yaml to a string that looks something like '[ahref="http://example.com"]Example.com[/a]'. The brackets make it easier to change after the html is generated. Further down in the code I use pygments to generate the html
htmlpage = highlight(yamldata,lexer, HtmlFormatter(full=True, title=yamldata['TITLE']))
Now I convert the href that I created above to a real href with:
webpage = htmlpage.replace(''', '').replace('ahref', 'a href').replace('[','<').replace(']','>').replace('"','"')