ergo / pyramid_apispec Goto Github PK

It looks like most versions of pyramid_apispec are pulling the latest build of apispec which is (in this particular case) causing code to break even if bound to a specific version of pyramid_apispec.

Specifically the replacement of spec.definition() to spec.components.schema()
and
spec.add_path() to spec.path().

In relation to the current documentation and APISpec object.

Could you bind to a specific stable version of apispec to correct the issue?

Is it possible to change the UI of default swagger and use Redoc?

Can you create a new release? That way I don't have to maintain a vendored copy of the match_param changes. :)

As an aside, are you agreeable to dropping Python 2.x support?

It would be great to have an opportunity to use local assets.

pyramid_apispec don't handle routes with regular expression. For example:

config.add_route('resource.item', '/api/resource/{id:\d+}')

Swagger UI produces the following curl:

curl -X DELETE "http://localhost:6544/api/resource/{id:\d+}" -H "accept: application/json"

Hey there! 😊
I wondered whether it would be possible to overwrite the paths that are currently taken from the decorator to something self-defined..

My problem is that my path is path='/api/exercises/{exercise_id:\d+}/{user_id:(\d+)+\/?}' but that should be kinda internal and I would like to overwrite this with path='/api/exercises/{exercise_id}/{user_id}' so I do not need to show my regex matches to the API user.

From the OpenAPI 2.0 standard:

paths:
  /users: <-- this 
    get:
      summary: Returns a list of users.

Currently this does not seem to be possible, atleast not from what I have tried... 😄
I would therefore suggest adding interpretion for the parameter path like this:

"""
---
path: 
  /api/exercises/{exercise_id}/{user_id}:
     get:
      tags:
        - "My API"
      summary: "return an exercise for given student"
      description: ""
      operationId: "exercise_student_get"
      produces:
        - "application/json"
      responses:
        200:
          description: successfull return of the exercise
          schema:
            $ref: "#/definitions/ExerciseStudent"
"""

Would that be possible?
All the best
Chris

When a route pattern includes placeholders that are used as predicates in a view's match_param, this means there can be multiple view functions with different documentation and unique URLs, however currently only one view's documentation is loaded and the path documented with APISpec includes placeholders the end user likely does not know about.

For example, the following route and views would currently only document as a single endpoint (/foo/{id}/{view}) when I think it should document two endpoints (/foo/{id}/bar and /foo/{id}/baz).

config.add_route("foo", "/foo/{id}/{view}")

@view_config(route_name="foo", match_param="view=bar")
def foo_bar(request):
    """
    ---
    description: bar a foo
    """

@view_config(route_name="foo", match_param="view=baz")
def foo_baz(request):
    """
    ---
    description: baz a foo
    """

Edit: Grammar/clarity

I have a situation where I need to user swagger format 3.0.0, can I still use this SwaggerUI integration? Because a valid file(compiles fine in the swagger editor) is not being compiled in my pyramid application SwaggerUI. I'm missing some configuration?

For the demo app, in the lower right corner of the Swagger UI, there is a red icon labeled "Error". Clicking the icon opens a new browser tab with the URL and content:

https://online.swagger.io/validator/debug?url=http://0.0.0.0:6543/openapi.json

{"schemaValidationMessages":[{"level":"error","message":"Can't read from file http://0.0.0.0:6543/openapi.json"}]}

I am unable to create / generate API specification using marshmallow schema containing field having type as list/array of String.

Details : My local version details -

"pyramid_apispec==0.3.3", "marshmallow==3.6.1 , pyramid==1.10.4 , python == 3.7.3"

My code looks like :

import marshmallow
from marshmallow import fields, validate

class BaseSchema(marshmallow.Schema):
class Meta:
strict = True
ordered = True

class MyCustomSchema(BaseSchema) :
app_ids = fields.List(fields.String())

Here when I tried to access api specification http://localhost:8080/api-explorer . I got following error –

File "d:\saurabh\june-venv\lib\site-packages\apispec\core.py", line 143, in schema
ret.update(plugin.schema_helper(name, component, **kwargs) or {})
File "d:\saurabh\june-venv\lib\site-packages\apispec\ext\marshmallow_init_.py", line 169, in schema_helper
json_schema = self.openapi.schema2jsonschema(schema_instance)
File "d:\saurabh\june-venv\lib\site-packages\apispec\ext\marshmallow\openapi.py", line 657, in schema2jsonschema
jsonschema = self.fields2jsonschema(fields, partial=partial, ordered=ordered)
File "d:\saurabh\june-venv\lib\site-packages\apispec\ext\marshmallow\openapi.py", line 681, in fields2jsonschema
property = self.field2property(field_obj)
File "d:\saurabh\june-venv\lib\site-packages\apispec\ext\marshmallow\openapi.py", line 433, in field2property
ret["items"] = self.field2property(field.container)
AttributeError: 'List' object has no attribute 'container'

The docstring example for the response schema in README.md does not work with the current master branch because apispec changed how to reference schemas in apispec 2.0. When using the example format of $ref: "#/definitions/BarBodySchema" I get the following error:

Could not resolve reference because of: Could not resolve pointer: /definitions/BarBodySchema does not exist in document".

Per the upgrade docs (and my testing) I think the docstring should look like this:

@view_config(route_name='foo_route', renderer='json')
def foo_view():
    """A greeting endpoint.

    ---
    x-extension: value
    get:
        description: some description
        responses:
            200:
                description: response for 200 code
                content:
                    application/json:
                        schema: BarBodySchema
    """
    return 'hi'

Hi @ergo ,

thank you very much for that lib. I integrated it nicely working into a playground project, rendered it with a different yaml lib

    # this requires `apispec==1.0.0b3`
    spec = APISpec(title="Some API", version="1.0.0", openapi_version='3.0.0', plugins=[MarshmallowPlugin()])
    # you can further mutate the spec dict to include things like security definitions
    my_spec = spec.to_dict()
    return Response(pyaml.dump(my_spec, safe=False, force_embed=False, vspacing=[2, 1], string_val_style='"'))

convert that output via widdershins

widdershins \
				--headings 4 \
				--resolve true \
				--search false \
				--language_tabs \
					'shell:Bash' \
					'javascript:JavaScript' \
					'python:Python' \
					'ruby:Ruby' \
					'java:Java' \
				--outfile var/index.html.md \
				--verbose \
				--expandBody true \
				var/openapi_direct.yaml

and put that index.html.md into Slate. Much wow ;)

Now I integrated it into my real project, which is using Cornice. Unfortunately this does not seem as an easy pick.

# Cornice `service.name` becomes `route_name` of Pyramid
c1_login_service = Service(name='c1_login',
                           path='/auth',
                           description='Validate a JWT and create a session for us.')

@c1_login_service.post(accept='application/json',
                       schema=PostJwtSchema,
                       validators=(body_validator,),
                       require_csrf=False)
def checkout_authentication(request):
    """
    Validate a JWT and create a session for us

    ---
    x-extension: value
    post:
      # headline/name of the resource (renders as `h2`)
      ...

I can register that route, but the docblock is not being read.

Do you have any guess, or hint where to go?

Cheers

Hi,

I'm having trouble with the schema example rendering, where I have a field that is a Oneof type of schema, the json generation is working properly, because in the swagger editor it is being rendered properly, however in the api-explorer is not working as should be. I'm using the latest version of the project.

The Schema:

The example rendered:

The example rendered in the swagger editor:

The json generated:

{"paths": {"/api/v1/state/{session}": {"put": {"parameters": [{"name": "session", "in": "path", "required": true, "schema": {"type": "string"}, "description": "session parameter"}], "tags": ["Browser Remote Storage"], "summary": "Session Put", "description": "\n    Inserts the payload into a section\n    for the logged user.\n    ", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/BaseLoanRequestSchema"}}}}, "responses": {"400": {"description": "", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BaseResponseErrors"}}}}, "200": {"description": "Json return without any schema pattern", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/JsonResponse"}}}}}}}}, "info": {"title": "Browser Remote Storage", "version": "4.0.0", "description": "\n        Storage for non structured data separated by sessions and by the user id inside auth_tkt\n        cookie.\n        "}, "openapi": "3.0.2", "components": {"schemas": {"Company": {"type": "object", "properties": {"type": {"type": "string", "default": "type: company"}, "cnpj": {"type": "string"}}, "required": ["cnpj", "type"]}, "Person": {"type": "object", "properties": {"type": {"type": "string", "default": "type: person"}, "cpf": {"type": "string"}}, "required": ["cpf", "type"]}, "Borrower": {"type": "object", "properties": {}, "oneOf": [{"$ref": "#/components/schemas/Company"}, {"$ref": "#/components/schemas/Person"}], "discriminator": {"propertyName": "type", "mapping": {"company": "#/components/schemas/Company", "person": "#/components/schemas/Person"}}}, "BaseLoanRequestSchema": {"type": "object", "properties": {"borrower": {"$ref": "#/components/schemas/Borrower"}, "uuid": {"type": "string", "format": "uuid", "readOnly": true}, "requestor": {"$ref": "#/components/schemas/Person"}}}, "BaseResponseErrors": {"type": "object", "properties": {"errors": {"type": "array", "items": {"type": "object"}}, "status": {"type": "string"}}}, "JsonResponse": {"type": "object", "properties": {}}}, "securitySchemes": {"AuthTkt": {"type": "cookie", "in": "header"}}}, "servers": [{"url": "http://0.0.0.0:8080"}]}