This is applicable only to API projects, which include Swagger by default. Web projects may add Swagger if they wanted, but it’s of minimal value.
If you’re building an API, proper documentation is just as important as performance. Unfortunately, maintaining docs is time consuming and they frequently become outdated.
In order to encourage full documentation of endpoints in APIs built with Grind, Grind has a Swagger provider that provides first class Swagger integration into Grind routes via a /swagger.json
endpoint.
By building Swagger docs directly into routes, it reduces time and effort involved in creating and maintaining API documentation.
First, add the grind-swagger
package via your preferred package manager:
yarn add grind-swagger
Next, you’ll need to add SwaggerProvider
to your app providers in app/Boostrap.js
:
const app =appproviders
Grind will only expose routes that are explicitly documented for Swagger.
You can document your routes for Swagger by passing a swagger
object to third param when registering a route:
approutes
The previous example uses the Swagger spec directly, which is a bit verbose and repetitive. Fortunately, Grind’s implementation of Swagger can infer quite a bit for you for you:
approutes
Based on this, the following can be inferred:
state
is a required string parameter that appears in the URLletter
is an optional string parameter that may appear in the URLlimit
andoffset
are optional query string parameters
letter
is inferred as optional due to the route param’s trailing?
.state
is a non-optional parameter, making it required.- If no type is provided, the following rules are used (in order):
- If the name starts with
has_
oris_
, the type is inferred asboolean
- If the name is
id
or ends with_id
, the type is inferred asinteger
- All other parameters types are inferred as
string
- If the name starts with
limit
andoffset
are inferred as optional query parameters because they don’t appear in the route path and this is aGET
request.- For non-
GET
requests, parameters that don’t appear in the route path are inferred as requiredbody
parameters. - All rules that are explicitly defined will take precedence over any inferred rules.
You can help inference by ‘teaching’ it. This is useful for common keywords that have the same type, but will differ in their descriptions.
SwaggerSwaggerSwaggerapproutesapproutes
Without teaching, featured
, limit
and offset
would have had their type inferred as string
. By teaching, their type is correctly inferred as boolean
, integer
and integer
respectively.
No one wants to clutter their code with a bunch of repetitive documentation. To avoid this, you can define shared parameters (and groups of parameters) to use within your routes:
// Register a single parameterSwagger// Register a group of parametersSwagger// Now you can reuse these quickly:approutes
Shared parameters can also take advantage of inference, allowing for far more concise and readable code:
SwaggerSwaggerapproutes
Swagger.parameter
and Swagger.learn
have a bit in common in that they can share common documentation between multiple routes, however they differ in how they should be used:
- Shared parameters should be used when you’re looking to include documentation for a parameter that is shared between different routes ‘as-is’.
- Teaching should be used when you’re just trying to improve inferring and you’re still planning to describe your parameters.
Here’s an example of shared parameters working together with teaching:
Edit// Documentation of what “featured” is will change// from route to route, so we just teach the typeSwagger// Documentation for pagination is shared, so we// define the group of params and reuse as-is.Swaggerapproutesapproutes