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
By building Swagger docs directly into routes, it reduces time and effort involved in creating and maintaining API documentation.
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:
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:
Based on this, the following can be inferred:
stateis a required string parameter that appears in the URL
letteris an optional string parameter that may appear in the URL
offsetare optional query string parameters
letteris inferred as optional due to the route param’s trailing
stateis a non-optional parameter, making it required.
- If no type is provided, the following rules are used (in order):
- If the name starts with
is_, the type is inferred as
- If the name is
idor ends with
_id, the type is inferred as
- All other parameters types are inferred as
- If the name starts with
offsetare inferred as optional query parameters because they don’t appear in the route path and this is a
- For non-
GETrequests, parameters that don’t appear in the route path are inferred as required
- 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.
offset would have had their type inferred as
string. By teaching, their type is correctly inferred as
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:
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