search

clowder-framework / clowder

A data management system that allows users to share, annotate, organize and analyze large collections of datasets. It provides support for extensible metadata annotation using JSON-LD and a distribute analytics event bus for automatic curation of uploaded data.
https://clowderframework.org/
University of Illinois/NCSA Open Source License
37 stars 17 forks source link

Missing swagger documentation #151

Open robkooper opened 3 years ago

robkooper commented 3 years ago

Describe the bug It looks like the documentation for the /api/users is missing from swagger, ran a little script to check. Created a list with checkboxes, can be fixed with many small PRs.

#!/bin/bash

grep '^ */' public/swagger.yml | sed 's#^ */\(.*\): *$#/api/\1#' | sed 's/{\([^}]*\)}/:\1/g' | sort > swagger.api
grep '^[A-Z]* */api/' conf/routes | sed 's#[A-Z]* *\([^ ]*\).*#\1#' | sort > routes.api

diff swagger.api routes.api > docs.diff

echo "MISSING IN SWAGGER"
awk '/^> / { print "- [ ]",$2 }' docs.diff

echo ""
echo "EXTRA IN SWAGGER"
awk '/^< / { print "- [ ]",$2 }' docs.diff

Resulting in the following errors:

MISSING IN SWAGGER

GEOSTREAMS

EXTRA IN SWAGGER (might be just wrong parameter)

bodom0015 commented 3 years ago

I may be confused, but I see a lot of these entries already listed under swagger, such as the /collections endpoints and the ones under /logos. There are indeed a few missing endpoints (e.g. /previews and friends), but is it possible that your script isn't matching anything starting with /api? The script output also does not include the HTTP method (GET / POST / etc) so it may be that I'm missing something there.

The Swagger spec doesn't include that base path.. does that prefix maybe need to be stripped off when checking the diff?

I am checking off things under "missing" that are already present in the Swagger spec. If there are specific bits missing from the items I'm checking off, let me know. This should at least significantly whittle down the list of endpoints that are "missing".