I have a project hosted on GitHub. To document the API I am using the OpenAPI spec. Now I want to add a link on readme.md (on GitHub) that refers my visitors to the OpenAPI document for good user experience.
Far as I see I have two solutions:
http://editor.swagger.io/?raw=https://raw.githubusercontent.com/path/to/file.yaml
https://app.swaggerhub.com/apis/(username)/(api-name)/(api-version)
Both approaches are working, but they both open with an editor on left side that shows the content of YAML file and is, IMHO, wasting a significant screen space. Not really what I want. Is there an option to display the OpenAPI document without editor opened? Just similiar what is done for https://petstore.swagger.io/ which comes without editor opened.
Or ... is there maybe an option available to display the OpenAPI document on GitHub directly?
Thanks, Christoph
If you use SwaggerHub, replace /apis/ with /apis-docs/ in the URL to view just the API docs without the editor part. For example:
https://app.swaggerhub.com/apis-docs/swagger-hub/registry-api/1.0.47
Or if your OpenAPI definition is hosted elsewhere (e.g. on GitHub), you can use
https://petstore.swagger.io/?url=https://path/to/file.yaml
to load it into the public Swagger UI demo. Swagger UI renders API docs without the editor part.
Related
I have started to use Spring Rest Docs for a project but other APIs in the company are still using Swagger/OpenAPI which has led to a style inconsistency.
The usual Swagger view (e.g. https://petstore.swagger.io) has collapsible sections for each url and CSS colouring GET/POST/PUT/DELETE etc.
I should be able to customise the asciidoctor with a line in the adoc
:stylesheet: custom.css
Is there an existing template for Spring Rest Docs that gives an output similar to what the default Swagger output looks like?
Can you add javascript to the asciidoctor output to animate some of the documentation like collapsible url sections?
This is really any Asciidoctor question so you might want to tag it as such.
Is there an existing template for Spring Rest Docs that gives an output similar to what the default Swagger output looks like?
Not that I am aware of.
Can you add javascript to the asciidoctor output to animate some of the documentation like collapsible url sections?
Yes, you can add JavaScript to the HTML that's generated by Asciidoctor. One approach is described in the answers to this question. Another approach is to use a DocinfoProcessor to inject the JavaScript into the <head> of the generated HTML. One advantage of the latter approach is that it allows the functionality to be packaged as a dependency and reused. You can see an example of a fairly simple DocinfoProcessor here.
Take a look at this Github project: https://github.com/ePages-de/restdocs-api-spec
A few teams at my company are using this to generate OpenAPI documentation from our Sprint Rest Doc tests.
Context
You can create a Gist on GitHub and embed it on your web page: embedding Gists.
This is an example of a randomly chosen Gist: tap.groovy.
Question
Is embedding also possible with other code files from GitHub, for example with this randomly chosen C# file ICommand.cs which is not a Gist?
You can try https://emgithub.com, which does exactly what you want.
To embed the example file ICommand.cs in your question, you can just add "em" before "github.com" in the address bar, then press Enter.
Then you can get a script tag like this:
<script src="https://emgithub.com/embed-v2.js?target=https%3A%2F%2Fgithub.com%2Fdotnet%2Fcorefx%2Fblob%2Fmaster%2Fsrc%2FSystem.ObjectModel%2Fsrc%2FSystem%2FWindows%2FInput%2FICommand.cs&style=default&type=code&showBorder=on&showLineNumbers=on&showFileMeta=on&showCopy=on"></script>
Note if you simply click Run code snippet in StackOverflow, the copying button at top right corner may not work. Running it outside SO would work fine.
Unlike other websites that do similar work, EmGithub.com is a static site hosted on Github Pages. Fetching target files and highlighting are done on your browser.
Disclosure: I'm the developer of it :)
You can use https://gist-it.appspot.com/:
<script src="http://gist-it.appspot.com/https://github.com/dotnet/corefx/blob/master/src/System.ObjectModel/src/System/Windows/Input/ICommand.cs"></script>
There's a standard for embedding content from one website in another via a URL, called oEmbed. Unfortunately, GitHub is not a oEmbed provider, i.e. it doesn't support oEmbed for its URLs.
I found a proxy service, Oembed Proxy for GitHub,
which adds oEmbed support for GitHub's code URLs. You pass a GitHub URL as a parameter to the proxy's URL and a resulting URL can be be pasted in another website, assuming that website supports embedding oEmbed links.
Another obstacle is that not every website supports embedding oEmbed URLs. According to the proxy's documentation, notion is one website that supports them. I did some research and looks like it should be possible to add oEmbed support to e.g. wordpress or jekyll.
This answer provides a very limited solution, due to small adoption of oEmbed. I thought it would be worth to spread the word nonetheless.
Another possible service is https://github.com/finom/github-embed. It seems to be unmainted by now for about 2 years, but gist-it seems to be unmaintained for even 6 years. I've tried neither, though.
You can use gistYard
<iframe src="https://gistyard.piyushdev.xyz/emd.html?lang=&from=0&to=&code=https://raw.githubusercontent.com/dotnet/corefx/master/src/System.ObjectModel/src/System/Windows/Input/ICommand.cs&edit=true&dm=off" width="100%" height="330" frameborder="0"></iframe>
It provides features like changing theme , cutting code directly from raw , edit mode , custom styling and others.
I am creating a new template and then a page from SCRATCH in CQ5. But I can't find the option to add my own CSS/images/JS to the page.
I mean a place to add/upload the actual files.
All the tutorials I've seen talk only about creating a template based on an existing template. Is there any tutorial on how to create the page from scratch ?
Your CSS and JavaScript go into nodes under /etc/designs/[your project's name]/clientlibs. (Ordinarily, you would set the page property cq:designPath of your content's home page to be /etc/designs/[your project's name] to point to this.) It's common practice to set up a subfolder of clientlibs called default, where your general-purpose style sheets and JavaScript go; you can set up other clientlibs for special-case script and style sheets. The simplest way to incorporate your script and style sheets into your page template is the <cq:includeClientLib> JSP tag.
The Adobe docs on clientlibs will also be useful to you, and explains how to use the tag.
#David , thanks for your answer, but for now, I got a better way to add and then use external files using WebDAV with CQ5.
The basic integration of WebDAV with CQ5 application is mentioned in this page
I looking for either an open source (or otherwise) php script/library/code that will provide me with a similar email composer that Mailchimp and Campaign Monitor have.
I've played around with lots of wysiwyg editors (eg: tinymce, ckeditor) but, they don't work very well for allowing users to compose emails.
Mosaico Editor is the first open source email template builder of this kind (AFAIK).
You can find a free to use deployment (working also as live demo) at http://mosaico.io and you can get sources at https://github.com/voidlabs/mosaico
I choose blocks from a set defined by the "master template", then you fill you contents and change their styles in a WYSIWYG style. If you're on a large window you can also have live preview for the mobile version.
The master template defines what are the blocks, what you can edit and what you can style and it contains any html trick to make it compatible with most clients: this means you can change the editor behaviour a lot by simply writing a new master template.
It is 99% javascript (IE10+, and any other modern browser) and depends on server-side functions only to do "final inlining" and "image upload/resizing"
Next generation tool for building templates without coding
Grapejs official site
GrapesJS is an open-source, multi-purpose, Web Builder Framework which combines different tools and features with the goal to help you (or users of your application) to build HTML templates without any knowledge of coding. It's a perfect solution to replace the common WYSIWYG editors, which are good for content editing but inappropriate for creating HTML structures. You can see it in action with the official demos, but using its API you're able to build your own editors.
I'm in the process of building one but as a designer it is a work in progress! I'd suggest looking at PHP template engines. They have a similar functionality. Most however will use php variables inside the html page instead of tags.
Another oprion is to check out Perch it is officially a CMS, but is really lightweight and might get the job done for you.
Hope that helps even though it is a year after you posted the question...
EDIT: Actually just stumbled across this thread which links to the new CKEditor - looks pretty cool.
We've been trying to work with Liferay CMS to create Web Content (liferay terminology). The content is versioned in the sense, each time we change the content and publish it, the version increments.
This has an impact on the URL which is publicly exposed, and we're facing the trouble of changing the URL on content change.
Is there a way of getting a published URL that reflects change in content without changing the URL?
You could use friendly urls in this case. Have a look at this post for some more info.
It doesn't appear that you are able to grab the latest journal content with any invokable URL because it requires a version number to be passed along with the request (otherwise it will just grab the first version not the last).
A work around would be to create a hook plugin that modifies the /journal/view_article_content action path with your custom implementation to return the latest article.
See Liferay's Portal Hook Plugins wiki page on how to create a hook.
Then see Mika's blog post on the specifics of overwriting a struts path.
Good Luck!