foobar@v1.23. D
Description of the code:
BaseService so we need to require it. Variables are declared with const and let in preference to var.BaseService so we need to import it.BaseService.route declares the URL path at which the service operates. It also maps components of the URL path to handler parameters.
base defines the first part of the URL that doesn't change, e.g. /example/.Our module exports a class which extends BaseJsonService
Returns the name of the category to sort this badge into (eg. "build"). Used to sort the examples on the main shields.io website. Here is the list of the valid categories. See section 4.4 for more details on examples.
+Returns the name of the category to sort this badge into (eg. "build"). Used to sort the examples on the main shields.io website. Here is the list of the valid categories. See section 4.4 for more details.
As with our previous badge, we need to declare a route. This time we will capture a variable called gem.
Once we have implemented our badge, we can add it to the index so that users can discover it. We will do this by adding an additional array examples to our class.
export default class GemVersion extends BaseJsonService {
+(4.4) Adding Documentation to the Frontend
+To render the shields.io website, we produce an OpenAPI 3 specification which describes the available badge endpoints. Then we use that specification to render the frontend.
+Once we have implemented our badge, we want to add it to the index so that users can discover it. We will do this by adding an additional object openApi to our class. This object contains an OpenAPI Paths Object describing the endpoint or endpoints exposed by this service class.
+// (1)
+import { pathParams } from '../index.js'
+
+export default class GemVersion extends BaseJsonService {
// ...
- // (1)
+ // (2)
static category = 'version'
- // (2)
- static examples = [
- {
- // (3)
- title: 'Gem',
- namedParams: { gem: 'formatador' },
- staticPreview: this.render({ version: '2.1.0' }),
- keywords: ['ruby'],
+ static openApi = {
+ // (3)
+ '/gem/v/{gem}': {
+ // (4)
+ get: {
+ // (5)
+ summary: 'Gem Version',
+ description:
+ '[Ruby Gems](https://rubygems.org/) is a registry for ruby libraries',
+ // (6)
+ parameters: pathParams({
+ name: 'gem',
+ description: 'Name of the Ruby Gem',
+ example: 'formatador',
+ }),
+ },
},
- ]
+ }
}
-- We defined category earlier in the tutorial. The
category property defines which heading in the index our example will appear under.
-- The examples property defines an array of examples. In this case the array will contain a single object, but in some cases it is helpful to provide multiple usage examples.
-- Our example object should contain the following properties:
+
-
+
There are four helper functions we can use to assemble Open API Parameter objects. These are:
-title: Descriptive text that will be shown next to the badgenamedParams: Provide a valid example of params we can substitute into
-the pattern. In this case we need a valid ruby gem, so we've picked formatador.staticPreview: On the index page we want to show an example badge, but for performance reasons we want that example to be generated without making an API call. staticPreview should be populated by calling our render() method with some valid data.keywords: If we want to provide additional keywords other than the title and the category, we can add them here. This helps users to search for relevant badges.pathParam - returns a single Parameter object describing a single path parameterpathParams - returns an array of path parameter objectsqueryParam - returns a single Parameter object describing a single query parameterqueryParams - returns an array of query parameter objects
+These four helper functions are documented in more detail at http://contributing.shields.io/module-core_base-service_openapi.html
+
+-
+
We defined category earlier in the tutorial. The category property defines which heading in the index our example will appear under.
+
+-
+
The keys of the openApi object are routes. In this case we only need to describe one route. In some cases, a service class can define more than one badge route. Open API doesn't have the concept of optional path parameters (more specifically, in: 'path' implies required: true) so if there are any optional path parameters in our route, our openApi object needs to describe two URLs: one without the optional parameter, and another with it.
+
+-
+
The HTTP method. Shields only allows GET requests, so this is always get.
+
+-
+
summary (required) is a short title or description of the badge. description is an optional longer description or additional documentation. We can use markdown or HTML syntax inside the description field.
+
+-
+
parameters is an array of Open API Parameter objects describing any parameters we can pass to this route. This array should include all path parameters included in the key that this value object describes and all relevant query parameters. As a minimum, we need to supply name and example. The example must be a valid example of a value we can provide for this parameter. In this case we need a valid ruby gem, so we've picked formatador. There are also optional keys we can pass. The code
+parameters: pathParams({
+ name: 'gem',
+ description: 'Name of the Ruby Gem',
+ example: 'formatador',
+})
+
+is equivalent to
+parameters: [
+ {
+ name: 'gem',
+ in: 'path',
+ required: true,
+ schema: { type: 'string' },
+ example: 'formatador',
+ description: 'Name of the Ruby Gem',
+ },
+]
+
+but we have used the helper function pathParams to imply some defaults and reduce the amount of code we need to write by hand.
Save, run npm start, and you can see it locally.
-If you update examples, you don't have to restart the server. Run npm run defs in another terminal window and the frontend will update.
+If you update openApi, you don't have to restart the server. Run npm run prestart in another terminal window and the frontend will update.
+Note: Some services define this information in an array property called examples. This is deprecated and we're in the process of converting them. New services should declare an openApi object.
(4.5) Write Tests
When creating a badge for a new service or changing a badge's behavior, tests
should be included. They serve several purposes:
@@ -379,7 +425,7 @@ will review your contribution.:user/:repo.
local-shields-io-production.yml (see
diff --git a/tutorial-releases.html b/tutorial-releases.html
index 17bebb9f2f..edad9bf5e6 100644
--- a/tutorial-releases.html
+++ b/tutorial-releases.html
@@ -79,7 +79,7 @@
public.requireCloudflare: true.