1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122<p align="center">
<img src="https://raw.githubusercontent.com/encode/apistar/master/docs/img/logo-200-square-light.png" alt="API Star" />
</p>
<p align="center">
🛠 <em>The Web API toolkit.</em> 🛠
</p>
<p align="center">
<a href="https://travis-ci.org/encode/apistar">
<img src="https://travis-ci.org/encode/apistar.svg?branch=master" alt="Build Status">
</a>
<a href="https://codecov.io/gh/encode/apistar">
<img src="https://codecov.io/gh/encode/apistar/branch/master/graph/badge.svg" alt="codecov">
</a>
<a href="https://pypi.python.org/pypi/apistar">
<img src="https://badge.fury.io/py/apistar.svg" alt="Package version">
</a>
<a href="https://pypi.python.org/pypi/apistar">
<img src="https://img.shields.io/pypi/pyversions/apistar.svg" alt="Python versions">
</a>
</p>
---
**Community:** https://discuss.apistar.org 🤔 💭 🤓 💬 😎
**Documentation:** https://docs.apistar.com 📘
---
API Star is a toolkit for working with OpenAPI or Swagger schemas. It allows you to:
* Build API documentation, with a selection of available themes.
* Validate API schema documents, and provide contextual errors.
* Make API requests using the dynamic client library.
You can use it to build static documentation, integrate it within a Web framework,
or use it as the client library for interacting with other APIs.
## Quickstart
Install API Star:
```bash
$ pip3 install apistar
```
Let's take a look at some of the functionality the toolkit provides...
We'll start by creating an OpenAPI schema, `schema.yaml`:
```yaml
openapi: 3.0.0
info:
title: Widget API
version: '1.0'
description: An example API for widgets
servers:
- url: https://www.example.org/
paths:
/widgets:
get:
summary: List all the widgets.
operationId: listWidgets
parameters:
- in: query
name: search
description: Filter widgets by this search term.
schema:
type: string
```
Let's also create a configuration file `apistar.yml`:
```yaml
schema:
path: schema.yaml
format: openapi
```
We're now ready to start using the `apistar` command line tool.
We can validate our OpenAPI schema:
```
$ apistar validate
✓ Valid OpenAPI schema.
```
Or build developer documentation for our API:
```
$ apistar docs --serve
✓ Documentation available at "http://127.0.0.1:8000/" (Ctrl+C to quit)
```
We can also make API requests to the server referenced in the schema:
```
$ apistar request listWidgets search=cogwheel
```
## Where did the server go?
With version 0.6 onwards the API Star project is being focused as a
framework-agnositic suite of API tooling. The plan is to build out this
functionality in a way that makes it appropriate for use either as a stand-alone
tool, or together with a large range of frameworks.
The 0.5 branch remains available on GitHub, and can be installed from PyPI
with `pip install apistar==0.5.41`. Any further development of the API Star
server would likely need to be against a fork of that, under a new maintainer.
If you're looking for a high-performance Python-based async framework, then
I would instead recommend [Starlette](https://www.starlette.io/).
---
<p align="center"><i>API Star is <a href="https://github.com/tomchristie/apistar/blob/master/LICENSE.md">BSD licensed</a> code.<br/>Designed & built in Brighton, England.</i>
<p align="center">
<img src="https://raw.githubusercontent.com/encode/apistar/master/docs/img/ident-44-square-light.png" alt="API Star" />
</p>