This repository contains an examples of OAS/Swagger API documentations with several tools and a guide to create good API documentation and use it to build a Mock server.
When two different teams develop backend and frontend separately - they both need a document stated the request and response data format. Of course, they make a deal in Slack for example and try to remember it. However, in this way your product become a "black box", which is highly difficult to support.
As a solution we propose to create a structured API documentation, which is not dependent on some specific technology. I mean that you don't need to learn some PHP or JavaScript to create such documentation. Nowadays, there are two popular formats: OAS (Open API Specification) and RAML (RESTful API Modeling Language). RAML is pretty cool, but OAS has bigger community and OAS became our choice. And unfortunately, we need to use outdated OAS2 format (aka "Swagger"), because OAS3 is not supported by numerous tools you will probably need it future.
You can find in this repo:
- Examples of swagger API documentation in OAS2, OAS3 in Yaml format. It's a multi-document structure with cross-docs references, to keep things DRY (Don't Repeat Yourself)
- Swagger UI viewer for API documentation
- PHP tool to merge multi-document yaml to a single document. Unfortunately available tools works only with single documents.
- PHP tool to generate fake object examples with Faker library.
To start with - you can clone this repository to some webserver. It uses static html and javascript, so you don't need any special server configuration. You will need composer package manager on the server.
git clone https://github.com/justcoded/swagger-tools.git /path/to/docroot/swagger
cd /path/to/docroot/swagger
composer installThat's it, you can open http://mydomain.com/swagger/ in browser and you will get a Swagger UI with our sample doc.
Or you can try to check swagger UI running nginx with docker like this:
docker run -p 8080:80 --name swagger-tools -v ./:/usr/share/nginx/html:ro nginxNow let's go to the examples folder. You can copy some folder to start with.
After that you will need to update index.html to point to your new docs by default:
<script>
window.onload = function() {
// Build a system
const ui = SwaggerUIBundle({
url: "./examples/jsonapi/swagger.yaml",
...As already mentioned we use OAS2 format, specification can be found here:
- https://swagger.io/docs/specification/2-0/basic-structure/
- https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
If you are new to the swagger format you will need to learn such declarations:
- Definitions Object (for Models and Objects)
- Path Object - for routes
- Parameter Object - for defining parameters
- Response Object - for response
Docs structure we propose to use:
- routes/ # Routes/Paths definitions grouped by section
- auth.yaml
- users.yaml
- models.yaml # Models/Requests definition
- params.yaml # Params, which are similar for paths in different routes groups
- responses.yaml # General responses definitions like 204, 401, 403, 404, 422, 500, etc.
- swagger.yaml # Main file, which includes other files
Because of limitations of OAS2 format we need to list ALL routes inside main file:
paths:
/auth/sign-in:
$ref: "routes/auth.yaml#/paths/login"
/auth/verify:
$ref: "routes/auth.yaml#/paths/verify"
/auth/password-reset:
$ref: "routes/auth.yaml#/paths/resetPassword"
...Having the examples I think all other things are self-explanatory.
We recommend to use WebStorm or PHPStorm (or any other Jetbrains IDE) to edit swagger yaml files. To have autocompletions on swagger identifiers and references you will need to install plugin called Swagger Plugin.
When you develop an API it's always a hard decision on what format JSON should be looks like. To solve this problem we suggest to follow JSONAPI specs: http://jsonapi.org/
In general, it defines that we need to transfer data in a format like this:
{
"data": [{ // collection or resource itself
"type": 'resource type',
"id": 'some id',
"attributes": {
// resource attribute
},
"relationships": {
'relation name': {
"data": { "type": "resource type", "id": "some id" }
}
// ...
}
}],
"included": [{ // data for related resources
"type": "related resource type",
"id": "some id",
"attributes": {
// related resource data
}
// ...
}],
"meta": {
// some other data like pagination info, tokens, etc.
}
}This format is good for JavaScript libraries such as React.js, Vue.js and Angular, because it's super easy to populate scope based on resource types.
JSONAPI has a lot of ready-to-use implementations: http://jsonapi.org/implementations/
Unfortunately, this specification doesn't answer how to form non-resource requests. Usually these are some actions, for example "search".
We suggest to define that we can transfer a document-type model of type "userInput", which can vary from route to route. Looks like this:
{
"data": {
"type": "userInput",
"attributes": {
// key/value pairs of user input data
}
}
}- Merge multi-document swagger YAML documentation
- Generate fake data to enums for mock servers
./cli/swagger-merge.php examples/v2.0/swagger.yaml > merged-swagger2.yaml
Add to your properties x-faker attribute:
swagger: '2.0'
definitions:
User:
type: object
properties:
id:
type: integer
format: int64
minimum: 1
email:
type: string
format: email
x-faker: email
first_name:
type: string
x-faker: firstName
last_name:
type: string
x-faker: lastName
Run command:
./cli/swagger-faker.php examples/merged/swagger2.yaml -n10 -r -c > swagger-faked.yaml
You will get:
definitions:
User:
type: object
properties:
id:
type: integer
format: int64
minimum: 1
email:
type: string
format: email
x-faker: email
enum:
- [email protected]
- [email protected]
- [email protected]
- [email protected]
- [email protected]
- [email protected]
- [email protected]
- [email protected]
- [email protected]
- [email protected]
first_name:
type: string
x-faker: firstName
enum:
- Denis
- Donna
- Elissa
- Brandyn
- Dino
- Linda
- Sadye
- Kenneth
- Michel
- Theo
...
required:
- id
- email
- first_name
- last_name
- profile
Of course, you can add this repository as dependency to your project, symlink swagger ui assets to your public repository and create your template inside your framework to print swagger ui interface, pointing to some generated doc.
As an example we created Yii extension, wrapping our PHP tools: https://github.com/justcoded/yii2-swaggerviewer