Load operations from reStructedText

[jimmy-lt]

Hi,

I'm working on a generating an operations dictionary from plain reStructuredText. This allow to get rid of the YAML an only use a plain doctstring to generate the OpenAPI structure.

The principle is as following:

def post_foo(self):
    """Add foo into the application.


    :body content application/vnd.api+json: Foo
    :body description: The foo to be added.
    :body required: Yes

    :deprecated: No

    :docs: A documentation for foo.
    :docs url: https://docs.example.com/api/v1/foo

    :id: foo

    :parameter test: A test parameter.
    :parameter test allow-empty: No
    :parameter test deprecated: No
    :parameter test explode: No
    :parameter test in: Query
    :parameter test required: Yes
    :parameter test style: Deep Object

    :response Ok content application/json: Foo
    :response Ok: The foo added to the application.

    """
    [...]

This cover so far most of the requirements for an Operations object and is fully functional on my side.

Note that in my current implementation, I take an extra function to lookup the HTTP code matching the provided textual representation (i.e Ok => 200).

The result from the above example is the following:

"/v1/foo": {
    "post": {
        "operationId": "foo",
        "requestBody": {
            "content": {
                "application/vnd.api+json": {
                    "schema": {
                        "$ref": "#/components/schemas/Foo"
                    }
                }
            },
            "description": "The foo to be added.",
            "required": true
        },
        "externalDocs": {
            "description": "An external documentation.",
            "url": "http://docs.example.com/api/v1/foo"
        },
        "responses": {
            "200": {
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Foo"
                        }
                    }
                },
                "description": "The foo added to the application."
            }
        },
        "parameters": [
            {
                "name": "test",
                "description": "A test parameter.",
                "allowEmptyValue": false,
                "deprecated": false,
                "explode": false,
                "in": "query",
                "required": true,
                "style": "deepObject"
            }
        ]
    }
}

Now I'm working on translating reStructuredText to CommonMark where applicable.

Is this something you would be interested in having in apispec? I can work on a pull request.

[lafrech]

This sounds interesting.

I can't tell right away if this would make it into the core but you're welcome to share your implementation here.

If it takes the form of a load_operations_from_docstring as in apispec.yaml_utils.py, then it will be usable in a plugin's path helper the same way.