Projects render API description files in YAML or JSON format into human-readable API documentation. API documentation typically consists of:
- a metadata page that displays the information on API version, description, security, and servers
- pages that describe individual operations API documentation can also have additional content independent of the description file, like quick start guides, security guides, or changelogs.
Both the metadata page, and the operations page have multiple interface elements that help you perform your tasks.
The project's API description files are available in both YAML and JSON formats.
To download an API description file:
- Navigate to an API's metadata page.
- In the Download API description section next to your preferred format, click the Download icon.
The file is downloaded to your machine.
The API's metadata page lists servers available to run the APIs operations.
To copy a server's URL:
- On an API's metadata page, in the Servers section, next to your preferred server, click the Copy icon.
You can now paste the server URL into another application.
Each operation has a code sample you can use to test the API, or copy and paste the request into another application.
To change the server URL:
- On an operation's page, in the code sample's top-left corner, select a server from the drop-down list.
The selected server is now displayed in the code sample.
API operation pages generate code samples for operations in one of several programming languages. You can select a language for all APIs in your project, or change it for a single operation.
To change the language of code samples globally:
- On an API's metadata page, in the Languages box, select a language for the code samples.
The code samples are now displayed in your chosen language for all APIs.
To change the language of a single operation:
- On an operation's page, in the code sample's top-right corner, select a language from the drop-down list.
The code sample is now displayed in your chosen language.
You can one-click copy code samples from API operation pages to use in your work. This function is especially useful with long code fragments.
To copy a code sample:
- In the top-right corner of the code sample, click the copy icon.
You can now paste the code into another application.
If you see an error or an inconsistency in a code sample, you can report it to the project's owner.
To to report a problem with a code sample:
- In the top-right corner of the code sample, click the exclamation mark icon.
- Describe the issue.
- Click Send.
Your message is sent to the organization that owns the project.
You can send feedback for each operation A project can have different types of feedback forms:
- thumbs up or down icons
- mood icons: satisfied, neutral or unsatisfied
- a rating in the form of icons, typically from 1 to 5 stars
- a numerical scale, typically between 1 and 10
- a comment
After you interact with a form (except the comment form), a text field is displayed. In this field, you can add more details to your feedback.
If you are logged in your project, your email address is automatically added to the feedback content. The owners of the project can use the address to follow-up with you on your comment. If are not logged in, or the project does not have login enabled, an optional Email field is displayed.
After you click Send, your feedback is submitted.
- Interact with pages
- Explore other ways you can interact with the user interface