meilisearch / meilisearch/documentation

API reference samples wrongly generated by Mintlify

Open
#3,464 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug fix/improvement tooling and maintenance
Dominant language
MDX
Stars
174
Forks
276
Avg merge
2d 1h
Merged PRs (30d)
6

Description

When https://github.com/meilisearch/documentation/pull/3446 will be merged, API references will be generated from an openAPI file by Mintlify.

To generate code samples in different languages, we use the x-codeSamples field that is handled by Mintlify

However, it seems that there is a bug on Mintlify side.
In docs.json we disabled the autogeneration, and we enforce the order of languages with:

"examples": {
  "languages": ["curl", "javascript", "php", "python", "java", "ruby", "go", "csharp", "rust", "dart", "swift"],
  "autogenerate": false
}

Although we defined this, for some routes like Webhook where some languages are missing in x-codeSamples (cf file: meilisearch-openapi-mintlify.json), but

  • are still generated (badly) by Mintlyfy
  • are not in the right order

Cf the PHP example that is not in the openAPI file, but still present

Image Image

I reported the bug to Mintlify, but I got no answer so far.
If not fixed on their side, a solution is to generate an example for any single language with Feature not available in this language if there is no code samples to provide from SDKs

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

Start with docs.json and the generated meilisearch-openapi-mintlify.json example referenced in the issue, then compare the Webhook routes' x-codeSamples entries with the rendered languages. Confirm that missing languages are still generated and out of order; done means the displayed samples follow the configured order and missing SDK samples are represented as unavailable, unless Mintlify fixes the reported bug.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api, documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.