netlify / netlify/open-api

Add model examples

Open
#191 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement specification
Dominant language
Go
Stars
323
Forks
133
Avg merge
2d 8h
Merged PRs (30d)
2

Description

It is very useful for developers to be able to visualize how a specific model, request body or response body might look instead of just seeing the attribute type.

There are several ways to do this, which might look differently depending on which HTML template we are using (see #182):

  • setting schema.example for each model attribute. This approach is probably the best. I think some HTML template might require this to be called x-example instead.
  • setting response.examples for each endpoint response.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review issue #182 and the existing model and endpoint response generation entry points. Compare the schema.example and response.examples OpenAPI options described here, including how the selected HTML template handles them. Done means the chosen approach produces visible examples for model attributes and request or response bodies.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, openapi
Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.