Define package responsibility

[marcgibbons]

Follow-up to: encode/django-rest-framework#4244

Options:

1. This package handles all things OpenAPI/Swagger related. CoreAPI currently converts OpenAPI to CoreAPI documents, while this prototype is focusing on generation of the OpenAPI spec from the CoreAPI doc. This package could potentially handle all of it. Django is supported as a contrib package, but other frameworks like Flask and Falcon could also be supported.
2. This project gets split: the converter gets merged into CoreAPI and the contrib bit gets pushed into django-rest-swagger.

Follow-up with @tomchristie.

[tomchristie]

Following on from some work on https://github.com/tomchristie/coreapi-hal I think I'm of the opinion that keeping things as modular as possible probably is a good plan.

Wasn't aware, but python does include a plugin system, so we can publish codecs and transports onto pypi, which once installed automatically become visible and usable to the command-line client, which is actually really rather nice.

So, I'd be happy to take responsibility for a bunch of packages, along these lines...

• coreapi
• coreapi-cli (Doesn't necessarily need to get split out immediately, but might be worth it)
• coreapi-openapi / coreapi-jsonhyperschema / coreapi-apiblueprint (Just the codecs)

[tomchristie]

In which case Django REST swagger would be a sensible package, rather than a set of different contrib packages all under one banner. (?)

[tomchristie]

I'll be taking a look at splitting out the codecs into installable packages either tomorrow or thurs.

[marcgibbons]

@tomchristie Sounds good! Happy to donate the dump portion of the codec.

I also wasn't familiar with plugins in setuptools... sounds promising if it can alleviate the tediousness of module detection and imports!

100% onboard for modularity / single purpose tools. In that case, I'll split out the SwaggerUIRenderer and OpenAPIRenderer for v2 of Django REST Swagger and can create a dependency on coreapi + upcoming coreapi-openapi plugin.

🚀

[tomchristie]

Nice!

[tomchristie]

Okay, so see the following:

• https://github.com/encode/hal-codec
• https://github.com/encode/jsonhyperschema-codec
• https://github.com/encode/openapi-codec
• https://github.com/encode/corehtml-codec

I've not pulled in any of your work to openapi-codec, so currently it's just the load() method. (Ie you can use coreapi as a client to APIs that publish a swagger spec) Pull request there very welcome.

I've also not yet split out the command line into coreapi-cli.

If you're using the command line client you can inspect the installed codecs, like so:

$ coreapi codecs show
Codecs
corejson "application/vnd.coreapi+json"
openapi "application/openapi+json"
jsonhyperschema "application/schema+json"
hal "application/hal+json"

[marcgibbons]

@tomchristie Great! I'll open a PR. I'd like to increase test coverage, but maybe for now, will port this over to the openapi repo to get the ball rolling.