feat: add user guide, license, and Python examples to API docs#15
Merged
Conversation
Mirrors the OpenEnzymeDB-api pattern (moleculemaker/oed-api) for the Swagger UI at /api/v1/docs: - Expand the FastAPI description with User Guide, Automatic Pagination technical note, CC BY 4.0 data license, and support contact sections. - Switch the Swagger UI syntax-highlight theme to "obsidian" so Python code blocks render with a neutral dark palette instead of purple. - Add URL examples and copy-pasteable Python (requests) snippets to the docstrings for /search, /typeahead, /curation-statuses, and /ec_lookup. Refs: #12
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #12.
Summary
Brings the CLEANDB-api Swagger UI to parity with the OpenEnzymeDB-api pattern requested in the issue:
description, rendered at the top of/api/v1/docsand/api/v1/redoc./search,/typeahead,/curation-statuses, and/ec_lookup.obsidianviaswagger_ui_parameters, addressing Le Yuan's note that the purple theme on OED looked off.Per Le Yuan's comment, the "Data Download" section from the OED pattern is intentionally omitted (full CLEAN dataset is too large to publish for direct download). The license matches OED (CC BY 4.0).
Scope: API repo only. The frontend FAQ "API" tab and License page mentioned in the issue live in the CLEAN frontend repo and will be handled separately.
Test plan
docker-compose up -dagainst a populated CLEAN DBhttp://localhost:8000/api/v1/docs— confirm User Guide / Pagination / License / Support render at the topobsidian(dark, neutral) themehttp://localhost:8000/api/v1/redoc— confirm the description renders the same content/searchPython example and run it against the deployed API at https://fastapi.cleandb.mmli2.ncsa.illinois.edu — confirm it returns data