https://github.com/artheus/swaggable
Simple language to generate larger swagger specs for code generation
https://github.com/artheus/swaggable
antlr go swaggable swagger swagger-generator yaml
Last synced: 3 months ago
JSON representation
Simple language to generate larger swagger specs for code generation
- Host: GitHub
- URL: https://github.com/artheus/swaggable
- Owner: artheus
- Created: 2018-08-06T15:39:09.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2018-11-07T09:13:27.000Z (over 6 years ago)
- Last Synced: 2025-01-15T04:15:53.940Z (5 months ago)
- Topics: antlr, go, swaggable, swagger, swagger-generator, yaml
- Language: Go
- Homepage:
- Size: 41 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Swaggable
Simple language to generate larger swagger specs for code generation.
The idea behind this is to create a minimal model definition for a CRUD api (incl api-client) which will expand into a larger specification which will act as the base for code generation. This way, people won't have to write much for just creating a simple Restful CRUD API service.
# Swaggable syntax
Since this implements a DSL for generating Swagger specifications, I feel the need to explain the syntax a bit.
## Types
All types specified in OpenApi are available. These are:
* string (this includes dates and files)
* number
* integer
* boolean
* array
* object
As parameters in the swaggable syntax there are two that stands out. It is `array` and `object`
### Arrays
The syntax for creating an array parameter in swaggable is `array stringArray` where `array` is the
parameter type identifier, `string` is the array item type and `stringArray` is the name of the parameter.
### Objects
You will never write `object` as the type of a parameter in Swaggable. You rather use the name of an other
component as the type identifier for the parameter. E.g: `MyComponent parameterName`
## Annotations
When is comes to indexed fields (eg. searchables) and string formats I decided to go with simple annotations.
There are several examples of this in `example/employers`. See the examples below, or the example model source for syntax.
The available annotations are:
* __required__ - flags a parameter as required
* __indexed__ - indexed field, which will be used for referring to a persisted component instance through the final API
* __format.*__ - the string formats specified in Swagger documentation
## Base components
As in the `example/employers` script, there are two base components. The meaning of having these is to
have extendable components that should not be part of the Swagger specification components.
Other components can extends these bases, and will in the output have all the parameters of the base.
From `example/employers`
```
base Entity {
number id `required indexed`
string created `format.datetime`
string updated `format.datetime`
Employee createdBy
Employee updatedBy
}
```
## Regular components
All of the regular components will turn up in the OpenApi output in `#/components/schemas`
Inheritance can work two ways. Either inherit from a base component, which in the output will only
add the parameters from the base component. Or inherit from a regular component, which till use
the OpenApi type inheritance, because both models will exist in the same specification.
From `example/employers`, a regular component inheriting from a base component:
```
comp Key < Entity {
Employee employee
Customer customer `required`
string position `required`
array notes
}
```