You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* feat: update split structure to be valid
* fix: use mapping instead of oneOf for explicit discriminator
* fix: Use openapi-cli v0.8.0 minimum (#46)
* chore: upgrade openapi-template version
* docs: Update readmes for v3 (#47)
> Generate an organized multi-file OpenAPI repository.
6
6
7
7
<center>
8
8
9
-
<imgsrc="./logo.png"widht="500px"/>
9
+
<imgsrc="./logo.png"width="500px"/>
10
10
11
11
</center>
12
12
13
+
## Who?
14
+
You! Hello. Do you need to write or contribute to an OpenAPI definition? If so, read on...
15
+
16
+
## What?
17
+
We recommend a docs-like-code approach to OpenAPI definitions:
18
+
- Write it using your favorite text-editor or IDE (we love VSCode).
19
+
- Organize it into multiple files and folders to make it easy to navigate.
20
+
- Store it using source control (such as GitHub).
21
+
- Continuously validate it using our free [openapi-cli tool](https://github.com/redocly/openapi-cli) or our free continuous validation service (coming soon).
22
+
- Bundle it (for a smaller footprint to use in other tools or for tools that do not support a multi-file format).
23
+
13
24
## Why?
14
-
There are a few advantages in hosting your API definition + docs on GitHub:
15
-
- Community engagement (PR's and issues)
16
-
- Hosting on GitHub pages (perfect uptime, CDN, Jekyll, custom domains with CNAME)
25
+
There are a few advantages in hosting your API definition on GitHub:
26
+
- Community engagement (PR's and issues -- if you have a public repo)
17
27
- Advertisment in the GitHub community
28
+
- Hosting on GitHub pages (perfect uptime, CDN, Jekyll, custom domains with CNAME)
18
29
- Revision history, branching, CI
30
+
- Review and approval workflows using Pull Requests
19
31
- Fast on-boarding time (developers and tech writers know how to use GitHub :smile:)
20
32
- Fully compatible with Redocly API Reference too
21
33
34
+
There are also some advantages to a multi-file YAML format OpenAPI definition:
35
+
- Reuse schema objects to keep things DRY (don't repeat yourself)
36
+
- Smaller diffs compared to JSON (especially for markdown descriptions)
37
+
- Easier to navigate
38
+
- Easier to edit with confidence
39
+
22
40
## Features
23
41
This generator helps to create a GitHub repo with the following features:
24
-
- Possibility to split a big OpenAPI definition into smaller files and bundle it for deployment
25
-
- Continuous integration/deployment on Travis
42
+
- Split a big (or small) OpenAPI definition into smaller files organized into folders
43
+
- Bundle it into a single file for deployment
44
+
- Continuous integration/deployment on Travis or Redocly Workflows
26
45
- Code samples as separate files
46
+
- Automate deployment of your OpenAPI definition and docs
27
47
- OpenAPI definition is validated after each commit
28
-
- OpenAPI definition + ReDoc deployed to Github Pages (you can use a custom domain)
29
-
- Live editing in your editor or `swagger-editor`:heart_eyes:
30
-
48
+
- Live editing in your editor of choice :heart_eyes:
49
+
50
+
## Structure
51
+
52
+
You will have a structure similar to this:
53
+
```
54
+
├── .redocly.yaml
55
+
├── LICENSE
56
+
├── README.md
57
+
├── docs
58
+
│ ├── favicon.png
59
+
│ └── index.html
60
+
├── openapi
61
+
│ ├── README.md
62
+
│ ├── code_samples
63
+
│ │ ├── C#
64
+
│ │ │ └── echo
65
+
│ │ │ └── post.cs
66
+
│ │ ├── PHP
67
+
│ │ │ └── echo
68
+
│ │ │ └── post.php
69
+
│ │ └── README.md
70
+
│ ├── components
71
+
│ │ └── README.md
72
+
│ └── paths
73
+
│ └── README.md
74
+
└── package.json
75
+
```
76
+
77
+
However, you can adjust it to any structure you prefer.
78
+
79
+
The `openapi` folder is where your OpenAPI definition will live. Inside there, and the sub-folders, there are `README.md` files to help guide you further. This is also where your entrypoint `openapi.yaml` will live.
80
+
81
+
The `components` folder is where you will organize sub-folders such as `schema` to define your schema.
82
+
83
+
The `paths` folder is where you will organize your paths. There will be a 'README.md' file in there with suggestions for how to organize it into specially named files (or folders) that use an `@` in place of a `/` (because files cannot have a `/` character in them). You will also be able to use path parameters by wrapping them in curly braces `{example}`.
84
+
85
+
The `.redocly.yaml` file is a universal configuration for various Redocly tools including the lint tool and reference doc engine.
86
+
87
+
## Commands
88
+
89
+
The generated repository includes installing a dependency for our `openapi-cli` tool which supports commands such as `validate`, `bundle`, and more. There are scripted shortcuts defined in the repository's `package.json`.
or use [`npx`](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b):
46
106
107
+
We'll use `npx` in this example. However, remove `npx` if you installed it globally.
108
+
47
109
```bash
48
-
npx create-openapi-repo<spec-root>
110
+
npx create-openapi-repo
49
111
```
50
-
-[Create GitHub repo](https://help.github.com/articles/create-a-repo/#create-a-new-repository-on-github) where your OpenAPI spec will live.
51
-
-[Clone your repo](https://help.github.com/articles/cloning-a-repository/) and execute the following command inside it:
112
+
113
+
You will be presented with some questions. You can create a new definition or use an existing definition to initialize your project.
114
+
115
+
Please note, if you do start a new one, remember to [create a GitHub repo](https://help.github.com/articles/create-a-repo/#create-a-new-repository-on-github) where your OpenAPI definition will live.
116
+
117
+
If you use the prior version of this generated repository, please read the following upgrade instructions.
118
+
119
+
#### Upgrading from a prior version
120
+
121
+
Migrate your repository from a previous structure of OpenAPI repo to this newer structure with our migration tool.
122
+
123
+
Run this in the root folder of your repo.
124
+
52
125
```bash
53
-
create-openapi-repo .
126
+
npx create-openapi-repo --migrate-2-3
54
127
```
55
-
- Commit and push your changes to the GitHub and follow instruction from `README.md` of your newly created repo.
128
+
129
+
Note: the migration tool does not migrate plugins automatically. You would need to manually add them to the `transformers` folder.
130
+
131
+
## Support
132
+
133
+
Thank you for wanting to support us. Here are some ideas how to support us:
134
+
135
+
* Star us
136
+
* Tell a friend or colleague about us (or Tweet about us)
137
+
* Write an article about it (and let us know) -- open an issue to let us know, with the link.
138
+
* Consider our commercial products if are looking for automation to ease the docs-like code workflow, hosting along with conveniences like custom domains, access controls and previews, API reference documentation, or a full developer portal: https://redoc.ly
0 commit comments