Comments (1)
@Roxie-32 here is my personal search from yesterday:
I've seen no markdown or other format to OpenAPI documentation. Every where there are import of OpenAPI in another documentation framework (like gitbook / slate).
It lead me to think we have to find a good tool to generate or edit OpenAPI documentation.
- Postman can already export to OpenAPI (eg. postman-to-openapi)
- there are specialized editors that renders a preview like Swagger Editor, and it seems acceptable to me, particularly if we use yaml. There is also a vscode extension
It has the advantage of really being a tool to write code, so really integrates well with git process
Even if we do OpenAPI I think we will need to integrate it in a larger documentation framework.
We mentioned gitbook yesterday and I've done a quick search for open-source alternatives.
- https://rust-lang.github.io/mdBook/index.html is a fork of gitbook. It only provides a CLI, not the nice rich text editor of gitbook. But vscode, for example, as good support for markdown with preview.
- slate is another API doc generator with existing importers (widdershins, swagger-to-slate)
- I see that other popular tools like sphinx have similar plugins
- docusaurus also seems like a good open source alternative and has openapi plugin
If we want to stick with postman, but be reviewable in github, we can imagine requiring (via an action) an openapi export on each PR.
My only solid take-away:
- we need to have open-api files
- we need another framework to generate documentation from markdown files (or the other way around)
from api-documentation.
Related Issues (20)
- Identify candidate object and fields to separate into includes
- Document the new documentation workflow
- Document the new multilingual text field `packaging_text_XX` that enables users to input the recycling instructions
- Document autosuggest for packaging
- Add documentation for Data Fields HOT 1
- Add documentation of the new API for the absence of fiber info on pack HOT 4
- Add a mention of the XML capability of the API
- Document 'no_nutrition_data' HOT 2
- Document the ability to send prepared nutritional values
- Document the Data Check API HOT 5
- Add a section at the beginning with a link to this project, explaining how to contribute and improve the documentation HOT 1
- Document the barcode/project change API
- Improve existing introduction for novice users HOT 2
- Add a mention of openfoodfacts-events in the API HOT 5
- GSOD'22 HOT 2
- Interview people and write down friction log
- Test gitbook / github / openapi intregration
- Add documentation for the Search V2 API
- Question about search & fields parameters
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from api-documentation.