I would like to use swagger for our project, which is rather big. Documenting the whole REST-API in one single yaml file would be too much, so I would like to split it into several yaml files.
First I tried to use Swagger UI simply by downloading it an opening its index.html. That works until the point that I split the yaml into multiple files, as I got CORS errors then. To circumvent them, I simply deployed the Swagger-UI Folder, with my projects yaml files inside it as artifact to my tomcat.
The folder structure of the artifact looked like this:
swagger_ui
├── index.html
└── api
├── root.yaml
├── paths
│ ├── path1.yaml
│ ├── path2.yaml
│ └── ...
└── schemas
├── schema1.yaml
├── schema2.yaml
└── ...
Now all CORS errors were gone, as my references are now all within the same origin (eg. "http://localhost:8080/swagger_ui")
So far, so good.
Now I wanted to have a simple way of editing the files using Swagger Editor.
In Swagger Editor, I click on File --> Import URL and import my root.yaml file. Now I get a bunch of errors saying the URLs to "paths" and "schemas" can not be resolved... Which makes sense, as I only imported root.yaml and the path and schema files are stored on a completely different server.
So my current approach is to deploy Swagger Editor alongside Swagger UI in my tomcat.
The current folder structure looks like this:
swagger_ui
└── index.html
swagger_editor
└── index.html
api
├── root.yaml
├── paths
│ ├── path1.yaml
│ ├── path2.yaml
│ └── ...
└── schemas
├── schema1.yaml
├── schema2.yaml
└── ...
I thougt I can use eg. "$ref: '../api/paths/path1.yaml'" to reference the the path1.yaml file from BOTH Swagger UI and Swagger Editor, but I get the Error:
Could not resolve reference: Tried to resolve a relative URL, without having a basePath. path: '../api/paths/path1.yaml' basePath: 'undefined'".
Aside from this error... Using ".." to go up one directory does not seem right in itself...
So the question is:
Which is the right way to set up a Swagger API Definition that has the following properties:
It is spread over multiple yaml files
It can be edited in Swagger Editor
It can also simply be visualized in Swagger UI
If my current approach is totaly wrong and there is a completely different approach, please tell me. It is no requirement to use tomcat or anything else I stated above. I just wanted to know if my approach makes any sense at all.
Related
I am building multiple poky-based images for different projects but using the same build directory (because it seems a bit overkill to have a new clone of yocto for every project).
But I happen to have my images conflicting with each other because of the .bbappend they define. For instance, I have two images that each extend the hostapd recipe in order to define their own configuration file.
Let me illustrate with an example. I have two layers that each define an image: first-project and second-project. Each has its own layer, because they belong to a different repository: meta-first-project and meta-second-project. And both use hostapd. So they projects look like this:
meta-first-project:
.
├── conf
│ └── layer.conf
├── recipes-connectivity
│ └── hostapd
│ ├── hostapd
│ │ └── hostapd.conf
│ └── hostapd_%.bbappend
└── recipes-first-project
└── images
└── first-project-image.bb
meta-second-project:
.
├── conf
│ └── layer.conf
├── recipes-connectivity
│ └── hostapd
│ ├── hostapd
│ │ └── hostapd.conf
│ └── hostapd_%.bbappend
└── recipes-second-project
└── images
└── second-project-image.bb
With a different hostapd.conf for each.
The conf/bblayers.conf file looks like this, including both layers:
conf/bblayers.conf:
BBLAYERS ?= " \
/home/user/Documents/yocto/poky/meta \
/home/user/Documents/yocto/poky/meta-poky \
/home/user/Documents/yocto/poky/meta-yocto-bsp \
/home/user/Documents/yocto/meta-first-project \
/home/user/Documents/yocto/meta-second-project \
When I run bitbake first-project-image, I want it to use the hostapd_%.bbappend in meta-first-project and not the one in meta-second-project. But my understanding is that both will be evaluated, meaning that meta-second-project/hostapd_%.bbappend will have an impact on my first-project-image, which I don't want.
Is there a way to solve that, or should I have two build folders (and download, build and duplicate everything there)?
For instance, I thought about checking something like this in the bbappend of hostapd in meta-first-project (pseudo-code):
if (${IMAGE_BASENAME} == "first-project-image") {
// write the whole bbappend here
}
Such that this bbappend is only considered when building the image first-project-image. However, ${IMAGE_BASENAME} does not seem to be set in the hostapd recipe...
Another idea, similar to COMPATIBLE_HOST and COMPATIBLE_MACHINE would be to define a COMPATIBLE_IMAGE variable, but that does not exist.
You can't change the content of individual recipes based on an image, that is a simple and unavoidable constraint from the way the system is built. The reason why is that the packages are constructed from the recipes long before the rootfs/image is built so it has no influence over it. All images use the same package set. You can reuse the same downloads, build directory and tree and simply change bblayers.conf to use one layer or the other and things will work but there isn't a way you can make both images work in the same configuration.
There are other options. You could separate out the hostapd change into two different recipes and then have each image include the correct content that way by including the right recipe. You could also tweak the image at construction time (see rootfs-postcommands.bbclass). You could specify two different DISTRO settings and switch between those, or maybe switch between configs depending on a MACHINE setting (making the hostapd recipe machine specific) but those two do require configuration changes between the images too. Multiconfig may or may not also be something which could help, it is hard to say from the information here.
There is no COMPATIBLE_IMAGE option as recipes are common to all images, that is just the way the system is designed and works, it doesn't build a new recipe set per image.
You can create your own COMPATIBLE_IMAGE variable and use it to conditionally append the conf file.
For example, in your meta-first-project/recipes-connectivity/hostapd/hostapd_%.bbappend:
SRC_URI_append = " ${#bb.utils.contains('COMPATIBLE_IMAGE', 'first-project-image', 'file://hostapd.conf', '', d)}"
And for your second image as well in
meta-second-project/recipes-connectivity/hostapd/hostapd_%.bbappend:
SRC_URI_append = " ${#bb.utils.contains('COMPATIBLE_IMAGE', 'second-project-image', 'file://hostapd.conf', '', d)}"
Now, the first conf file will appended to SRC_URI only if COMPATIBLE_IMAGE contains first-project-image.
You can define COMPATIBLE_IMAGE now anywhere you want, you can set it in local.conf for testing purposes or in your image recipe:
COMPATIBLE_MACHINE = "first-project-image"
You can use the COMPATIBLE_MACHINE variable now anywhere you want with the same principle.
Now, if you are appending to some hostapd tasks and using the conf file make sure to test on the variable before using it, and if hostapd understands directly the conf file and used without overriding some task you don't need to test on the variable.
Hello your use case seems compatible with BBMASK.
"Prevents BitBake from processing recipes and recipe append files."
Taken from documentation
With this variable, you can hide the bbappend you don't want to interact with your layer. Starting from your example, you'll have the following line in conf file of meta-first-project:
BBMASK += "meta-second-project/recipes-connectivity/hostapd"
But, if your two layers doesn't depends on each other, it is simpler to not reference them in their respective bblayers.conf. If the meta-second-project
is not necessary to build images provided by meta-first-project, simply remove meta-second-project from bblayers.conf.
I'm guessing from your post that the two projects are using the same MACHINE?
If they were different MACHINEs you'd have a lot more tools...
What I would do is probably create a hostapd-foo.bb with require hostapd.bb.
What is the recommended way to organize source files in a static site generator for generating pages? (I'm using Eleventy, but this may be useful for other SSGs)
pages
├── page1
├── index.md
├── page2
├── index.md
or
pages
├── page1.md
├── page2.md
Both directory structures should (or can) generate the following structure in the final site:
pages
├── page1
├── index.html
├── page2
├── index.html
Either way works in Eleventy, so it’s entirely a question of which way you prefer, which works best for how you like to arrange files and directories, and so on (https://www.zachleat.com/web/introducing-eleventy/#directory-structure-flexibility).
In other SSGs — notably Gatsby, Gridsome, and Hugo — one factor to keep in mind is that images for which you want special processing are best located in the same directories as the Markdown or other content files which “call” them, as relative file paths are required by the appropriate plugins or pipes:
Gatsby: “If any of the [image] paths used do not resolve to a file[,] Gatsby will not create child nodes, instead leaving the [path] value as a string.” (https://www.orangejellyfish.com/blog/a-comprehensive-guide-to-images-in-gatsby/)
Gridsome — “Only local, relative image paths will be compressed by Gridsome.” (https://gridsome.org/docs/images/)
Hugo — “The image is a Page Resource, and the [image] processing methods listed below does not work [sic] on images inside your /static folder.” (https://gohugo.io/content-management/image-processing/)
This is not a consideration with Eleventy, however.
Intro
I recently try to use Doxygen to document my ROS project. I didn't find a good way to create documentation for all my custom package "cleanly" with the rosdoc_lite package. In cleanly, I heard have a all the documentations linked in one big documentation (I hope that's clear enough).
Therefore, I try to generate a doc for all my ROS project with Doxygen. I have, right now, not a good idea how to structure my documentation, but I structure it as I learn Doxygen. I'm happy to have your advice if you want to share on a possible structure, or a way to use rosdoc_lite for all package.
My Problem
My main problem is I can not achieve to have all my h/py file documented. The problem occurs in one specific location.
Include
├── RStatus
│ ├── __init__.py
│ ├── Side.h #Documented
│ ├── State.h #Shown in file list but not documented
│ ├── State.py #Not shown in file list
└── Services
├── __init__.py
├── RobotServices.h #Documented
├── RobotServices.py #Documented
Each file has a #file, #brief and #author tag at the head of the file.
In addition, I tried to change the #file tag to #package in the State.py file. Doxygen create a empty namespace.
I'm stuck on this problem, and I don't know how to handle it.
If you want any more information, ask me!
Thx for your time !
As I try to make a small example of my problem, I found that I had 2 files with the same name located in two different package (#noob). I google it and I found that Doxygen can not distinguish automatically two files in two package. I did as ask in Doxygen docs (see here: http://www.doxygen.nl/commands.html#cmdfile) and everything works. (Each #file tag need to be unique. If needed, add dirpath to the file.)
In conclusion : My bad. -_-
Introduction:
So far I have not found any dummie guide on building a simple boilerplate. I am done using templates from other people. I have basic experience in building projects with Github, Atom, Markdown, Liquid, Jekyll & Bootstrap. So just need a hand with a couple of things.
Link to repo: https://github.com/bomengeduld/debadkamer
Other project I build succesfully, thanks to a template: https://github.com/werkbaar/werkbaar:
I like to stay as close as possible to this kind of rootdirectory, since I am used to work with that.
Target:
Im trying to establish an easy step by step "workflow" without to much Jargon, so also other starting designers can benefit from this. Can you help me with this?
What I have done so far:
1) Created a "NEW" repo on Github, with just a README file.
2) Cloned to GH desktop by clicking "Open in desktop"
3) Opened the project in Atom
4) Build the basic rootdirectory
5) Added gemfile:
a) Made a gemfile in directory
b) Opened rootdirectory in command
c) Installed bundle with following command: bundle install
Problem:
From this point on I get stuck and not sure which step to do first. In my assumption that bootstrap is a gem. I Added the gemfile. I did because at one installation tutorial they described it: https://github.com/twbs/bootstrap-sass
d) Installed bundle again with following command: gem install bundler
RootDirectoy:
├── _includes
| └── head.html
| └── nav.html
| └── header.html
| └── footer.html
├── _layouts
| └──default.html
├── assets
| ├── css
| ├── fonts
| ├── img
| └── js
├── .git
├── _config.yml
├── gemfile
├── gemfile.lock
├── index.html
└── README.md
For some reason the Assets folder is not added to my repo on github. probably because it does not contain any files yet.
Question:
How to Add Bootstrap 3 to my project & install the full gemlist needed?
Any other recommendations to make this a nice Clean Sheet?
Disclaimer: For those that like to assist:
Please explain as simple and practical as possible.
I'm a new learner of Pelican.
I have created my personal website including basic settings and some pages by using Pelican, and the following hierarchy has already existed on the local PC:
myblog/
├── author
├── content # Content file (Push on GitHub)
│ └── (pages)
├── output
├── theme
├── develop_server.sh
├── fabfile.py
├── Makefile
├── pelicanconf.py # Main settings file
└── publishconf.py
Unfortunately, I set the wrong sitename from the beginning when I install Pelican. Right now I'm struggling to change the incorrect sitename from "test" to "XXX's blog". I can rewrite sitename directly in the document called pelicanconf.py. But after that, there's no way to push it on GitHub. So the appearance of my website remains stable.
The only thing I could do is to update the page content again and again, but not the sitename. Because only the content folder is synchronized with my remote GitHub repository.
Is there anyway to change the sitename setting?