ergo / pyramid_apispec Goto Github PK
View Code? Open in Web Editor NEWPyramid plugin for openapi spec generation (using ApiSpec)
License: BSD 3-Clause "New" or "Revised" License
Pyramid plugin for openapi spec generation (using ApiSpec)
License: BSD 3-Clause "New" or "Revised" License
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?
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"}]}
It would be great to have an opportunity to use local assets.
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'
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?
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?
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
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
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"}]}
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'
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"
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
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.