Docs theme refresh, CLI tools, and work-behind-the-scenes


#1

Hi folks, a few things I wanted to draw attention to here. Firstly, the docs have gotten a really nice theme upgrade.

We’ll still want to add in a few things - syntax highlighting in the examples, including response schema information in the docs, and bringing back in interactive API requests.

The other thing that’s come in that I’ve not mentioned yet, is that the CLI is back with a coupla of initial commands. These are:

apistar validate <schema_file>

Validate an OpenAPI 3 schema. Gives you really nice colorized output with error indications when there’s an error in the schema.

apistar docs <schema_file>

Build the API docs given an OpenAPI 3 schema. Means that all the nice stuff we’re planning on getting into the API Star docs will be available for any framework or language so long as you have an OpenAPI Schema.

The plan is that a future release of REST framework will drop coreapi / coreschema for it’s docs, and instead use this package.

I guess I can also mention that I’m starting on a bit of product work around all this. I’ll keep folks up to date once there’s more that I can show publicly, but the MVP I’m aiming towards is around API Documentation, Schema Validation, API Mocking, and Dynamic Client Libraries. (*)

As it happens, the server component of API Star fits in a bit awkwardly with the other aspects, so will need to do some thinking around how best to document the different capabilities that API Star provides.

There’s a lot more work to do, but just wanted to start making some of these things a bit more public, as well as highlighting that there’s also a bit of work currently going on behind the scenes.

Cheers all,

Tom

(*)If you’re working with a team that you think might benefit from something in this space please do feel free to drop me a line tom@tomchristie.com and I’d be happy to talk things through in more detail. It could be any API team that’s using or considering using OpenAPI to spec out their services. (Not necessarily using API Star to build the server)


#2

Nice reintroduction of documentation, commands and general goals.

Even if the MVP is mostly validation related, maybe the documentation and schema could be an opt-in feature. In apistar-pydantic I needed to hardcode documented=False into the Route because I don’t have an working implementation of Route.generate_fields() to replace and pure APIStar crashes with unrecognized parameters.

Cheers