What is the difference between Editor and UI?
Editor is where you write or check the definition. UI is where readers browse the documented actions and examples. OpenAPI is the format of the definition. Keep that file as the source you can edit and review with your team.
Can browsing the docs send a real request?
The reference can be read as documentation. If interactive submissions are enabled and a server is configured, “Try it out” can also send real requests. For a docs-only review, your maintainer can disable those submissions across all actions. Check whether the viewer contacts an online validator before loading a private definition.
Remove keys, private addresses and customer examples before sharing the definition or the rendered reference. The published document can expose its examples even when sending requests is disabled.
What do you keep if you move the reference elsewhere?
Keep the OpenAPI definition and the sample files you maintain. The Editor and UI are available as open-source tools. Hosted team products have their own plans and permissions. You can render the same definition in a different viewer, but the file does not contain the actual behavior of your application.
How do you check whether the API description answers a reader’s question?
Draw a reference page for a fictional Read opening hours action. Give it to someone who has never seen your app. They should be able to tell what they send and what the reply means.
- Describe the inputSay that they supply one fictional location identifier. Include one example.
- Explain both repliesShow the opening time for a known location and describe the reply for an unknown location.
- Check the description on its ownAsk the reader to point out which reply their app should show in each case. This checks clarity on paper, without sending a request.