-
Notifications
You must be signed in to change notification settings - Fork 54
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Move doc files from main repo into docs repo #426
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,39 @@ | ||
#!/bin/bash | ||
# -*- coding: utf-8 -*- | ||
# Copyright European Organization for Nuclear Research (CERN) since 2012 | ||
# | ||
# Licensed under the Apache License, Version 2.0 (the "License"); | ||
# you may not use this file except in compliance with the License. | ||
# You may obtain a copy of the License at | ||
# | ||
# http://www.apache.org/licenses/LICENSE-2.0 | ||
# | ||
# Unless required by applicable law or agreed to in writing, software | ||
# distributed under the License is distributed on an "AS IS" BASIS, | ||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
# See the License for the specific language governing permissions and | ||
# limitations under the License. | ||
|
||
set -eo pipefail | ||
|
||
SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd ) | ||
|
||
|
||
command_exists() { | ||
# check if command exists and fail otherwise | ||
command -v "$1" >/dev/null 2>&1 || { | ||
echo "$1 is required, but it's not installed. Abort." | ||
exit 1 | ||
} | ||
} | ||
|
||
|
||
if [ "$#" -ne 1 ]; then | ||
echo "Usage: check_rest_api_documentation.sh FILE" | ||
exit 1 | ||
fi | ||
|
||
command_exists "node" | ||
command_exists "npx" | ||
|
||
npx @redocly/cli lint --config "$SCRIPT_DIR/redocly.yaml" "$1" |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,126 @@ | ||
#!/usr/bin/env python3 | ||
# Copyright European Organization for Nuclear Research (CERN) since 2012 | ||
# | ||
# Licensed under the Apache License, Version 2.0 (the "License"); | ||
# you may not use this file except in compliance with the License. | ||
# You may obtain a copy of the License at | ||
# | ||
# http://www.apache.org/licenses/LICENSE-2.0 | ||
# | ||
# Unless required by applicable law or agreed to in writing, software | ||
# distributed under the License is distributed on an "AS IS" BASIS, | ||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
# See the License for the specific language governing permissions and | ||
# limitations under the License. | ||
|
||
from apispec import APISpec # type: ignore | ||
from apispec_webframeworks.flask import FlaskPlugin # type: ignore | ||
from rucio.vcsversion import VERSION_INFO # type: ignore | ||
from rucio.web.rest.flaskapi.v1.main import application # type: ignore | ||
Comment on lines
+16
to
+19
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. what are the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The python script checking action claims these packages don't exist and fails the build 😔 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Maybe we could add them to the requirements instead - I guess they can be seen as part of the requirements for building the docs, so it makes sense that they'd need to be part of the
|
||
|
||
description_text = """Each resource can be accessed or modified using specially | ||
formed URLs and the standard HTTP methods: | ||
|
||
- GET to read | ||
|
||
- POST to create | ||
|
||
- PUT to update | ||
|
||
- DELETE to remove | ||
|
||
We require that all requests are done over SSL. The API supports JSON | ||
formats. Rucio uses [OAuth](http://oauth.net/) to authenticate all API | ||
requests. The method is to get an authentication token, and use it for the rest | ||
of the requests. Descriptions of the actions you may perform on each resource | ||
can be found below. | ||
|
||
### Date format | ||
|
||
All dates returned are in UTC and are strings in the following format | ||
(RFC 1123, ex RFC 822): | ||
|
||
``` | ||
Mon, 13 May 2013 10:23:03 UTC | ||
``` | ||
|
||
In code format, which can be used in all programming languages that support | ||
strftime or strptime: | ||
|
||
``` | ||
%a, %d %b %Y %H:%M:%S UTC | ||
``` | ||
|
||
### SSL only | ||
|
||
We require that all requests(except for the ping) are done over SSL. | ||
|
||
### Response formats | ||
|
||
The currently-available response format for all REST endpoints is the | ||
string-based format JavaScript Object | ||
Notation([JSON](http://www.json.org/)). The server answer can be one of the | ||
following content-type in the http Header: | ||
|
||
```text | ||
Content-type: application/json | ||
Content-Type: application/x-json-stream | ||
``` | ||
|
||
In the last case, it corresponds to JSON objects delimited by newlines | ||
(streaming JSON for large answer), e.g.: | ||
|
||
``` | ||
{ "id": 1, "foo": "bar" } { "id": 2, "foo": "baz" } ... | ||
``` | ||
|
||
### Error handling | ||
|
||
Errors are returned using standard HTTP error code syntax. Any additional info | ||
is included in the header of the return call, JSON-formatted with the | ||
parameters: | ||
|
||
``` | ||
ExceptionClass ExceptionMessage | ||
``` | ||
|
||
Where ExceptionClass refers to [`Rucio | ||
Exceptions`](https://github.com/rucio/rucio/blob/58efd21b5e21182df80bef3dbe8befa636e440b8/lib/rucio/common/exception.py). | ||
""" | ||
|
||
|
||
spec = APISpec( | ||
title="Rucio", | ||
version=VERSION_INFO["version"], | ||
openapi_version="3.0.2", | ||
plugins=[FlaskPlugin()], | ||
info={ | ||
"description": description_text, | ||
"license": { | ||
"name": "Apache 2.0", | ||
"url": "https://www.apache.org/licenses/LICENSE-2.0.html", | ||
}, | ||
"x-logo": { | ||
"url": "http://rucio.cern.ch/documentation/img/rucio_horizontaled_black_cropped.svg", # noqa: E501 | ||
"backgroundColor": "#FFFFFF", | ||
"altText": "Rucio logo", | ||
}, | ||
}, | ||
# See: https://swagger.io/docs/specification/authentication/api-keys/ | ||
components={ | ||
"securitySchemes": { | ||
"AuthToken": { | ||
"type": "apiKey", | ||
"in": "header", | ||
"name": "X-Rucio-Auth-Token", | ||
"description": "The Rucio Token obtained by one of the /auth endpoints.", # noqa: E501 | ||
}, | ||
}, | ||
}, | ||
security=[{"AuthToken": []}], | ||
) | ||
|
||
with application.test_request_context(): | ||
for view_func in application.view_functions.values(): | ||
spec.path(view=view_func) | ||
print(spec.to_yaml()) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe we should say this to be explicit
rucio_documentation
is clear enough imo, but it might be interpreted as if we have an actual folder namedrucio_documentation
, whereas[rucio documentation folder]
might be more easily interpreted as 'top-level Rucio documentation folder'There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If we're linking directly to the file anyways, is there any harm in going Full explicit and doing
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like the idea, but I feel that the
/
inrucio/documentation
could be interpreted as being part of the path, so it might be confusing