This project is for viewing and editing formal open-api type documentations for our API's.
Config files:
- src/config.js -- for frontend (mainly, you only need to change url path)
- public/restapi/constants.php -- for restapi (specify mysql connections)
To configure, create a symbolic link (or copy) from provided examples to config files like so:
# cd into src/
ln -s config.dev.example.js config.js
# cd into public/restapi/
ln -s constants.dev.example.php constants.php
Before setting up project, you may need to create database and create table with example data from:
/for-restapi/db_create.sql
If you need to, update configs as indicated in previous section and you can proceed with setup.
To set up this project, you will need:
- git
- npm
- php5.4+
- mysql5.4+
To install, run from gitbash in windows, or command line in linux/mac:
git clone [email protected]:gtw/docs.git
... install db if necessary ...
... do configuration ...
npm install
npm run build
To get changes:
git pull
npm update
npm run build
Navigate through available documents, using documents menu dropdown. You will see a new url in browser url bar, you can use that to reference specific document.
To edit documents, use edit menu dropdown.
To rename document filenames or their description(shown in upper menu) - use modify dropdown menu.
You can refer to openapi-gui documentation online for specific instructions of how to use this simple gui. Most of the functions are self-describing, so you can get to work quickly. The extra feature added to this app, is the button named Save to storage. Use that button to save the edited doc to our database through our restapi.
Worth noting, that you can export the contents of file, than copy all of that to some other editor if you find those more comfy. After editing in your favorite editor you can import back not only json, but also yaml format, by using UPLOAD section, load definition button. You can also edit raw contents there (remember it supports YAML too!).
- PHP5++,Mysql5.4++ for restapi and doc-handling
- React with Redux, axios, reactstrap(bootstrap for react) and other libs for frontend
- React Redoc for showing nice openapi documents (previously known as swagger.json)
- Openapi-gui for openapi doc editing