I have quite a large API with many wheels turning. Documenting all of these in one giant openapi.yaml file isn't easy for me so I decided to breakdown the docs to separate paths as shown in the screenshot below:
Now in my customer.yaml file I have the following routes:
/customers/new:
/customers/login:
/customers/logout:
And in my partner.yaml file I have the following routes:
/partners/new:
/partners/login:
/partners/logout:
Now I included the above two files into my final index.yaml file as below
paths:
- $ref: "./paths/partner.yaml"
- $ref: "./paths/customer.yaml"
But the final generated doc by the swagger-cli is adding the - character before the path references thereby resulting in a malformed unusable document.
How can I resolve this?
paths in OpenAPI is a map, not an array, so you can't use the yaml - syntax.
You need to include the pathItem keys in your top level file, and put the $refs to the relevant file or fragment of a file there.
For example:
paths:
/foo:
$ref: "./foo.yaml"
/bar:
$ref: "./paths.yaml#/paths/bar"
Related
Suppose I'm trying to break out an OpenAPI 3 specification into multiple files. I might do the following:
Spec/
requestBodies/
Blog/
post.yaml
__index.yaml
schemas/
requests/
post.yaml
__index.yaml
SampleAPI.yaml
// SampleAPI.yaml
openapi: 3.0.0
info:
...
servers:
...
security:
...
paths:
/blog/post:
post:
requestBody:
$ref: ./requestBodies/Blog/post.yaml
responses:
...
components:
securitySchemes:
...
requestBodies:
$ref: ./requestBodies/__index.yaml
schemas:
$ref: ./schemas/__index.yaml
// requestBodies/__index.yaml
Post:
$ref ./Blog/post.yaml
// schemas/__index.yaml
Post:
$ref ./requests/post.yaml
It seems like it would be a better idea to reference components based on where they will fall in the resolved component hierarchy: i.e. blog/post's requestBody would be '#/components/requestBodies/Post', rather than the relative location of the definition file: './requestBodies/Blog/post.yaml'. The latter seems more brittle and like it leaks the implementation details for how the API is split out into files. It's even worse when, say, a requestBody needs to reference a schema, and the choice is between declaring $ref: '#/components/schemas/Post' vs $ref: '../../schemas/requests/post.yaml'.
I have yet to see an IDE that works with OpenAPI that supports the former type of reference, however, while the latter type is readily supported. Is this a case of the IDEs just not being able to validate a specification multiple references deep in real time, or is the OpenAPI specification's intention/requirement that you either put your entire definition in one huge file or fill your definitions with relative file paths between components?
I am currently using ajv to validate some API inputs in node/express. The expected data is described in a .json schema file.
Now I would like to re-use this file to document my API, relying on swagger-ui-express and swagger-jsdoc.
There are quite many references to how to re-use an object definition in swagger, but all these descriptions suppose that definition is given in a "#swagger" comment block.
I simply don't see how to point to a local JSON file.
If my comment is shaped like this:
/**
* #swagger
* /init/user:
* post:
* description: Creates a user
* produces:
* - application/json
* parameters:
* - in: body
* name: create user
* required: true
* schema:
* $ref: 'schemas/initUserApi.json'
*/
(note this is an incomplete template, I want to focus on the problem), then the ultimate swagger output will throw an error:
Could not resolve reference: Tried to resolve a relative URL, without having a basePath. path: 'schemas/initUserApi.json' basePath: 'undefined'
I tried defining a 'components' section as described in this issue: Cannot reference a component schema defined in a separate file in Swagger, this does nothing.
I tried using absolute/relative file names, etc (also another suggestion here: How to use $ref in swagger file properly while working with swagger-ui-express and swagger-jsdoc), to no avail.
Is this possible? The goal is really to use a separate json file as a schema, as I would like to have a single source of information. I am not clear on how the swagger-ui-express/swagger-jsdoc chain works, would this json file need somehow to be served by my swagger web server (this is really for documentation running on localhost for now, no public/intranet publishing) ?
I have this piece of the spec to api, with about content in an external file:
paths:
/about:
$ref: ./api/about.yml#/about
In this way, about content doesn't load when I make a bundle using openapi-cli-tool. But, if I increase one auxiliar tag, the content is loaded.
paths:
/about:
whatever:
$ref: ./api/about.yml#/about
Using the whatever tag, the Swagger Editor show a Structural error, but without her don't load. Some tips?
Obs: I already saw some errors in the $ref tag in the openapi 3.0.
In Gridsome, how do you add local markdown files to the GraphQL layer, so that you can add graphql to vue components?
At the time of writing, the Gridsome docs for adding data from local files are empty.
The starter-blog also has a working implementation: https://github.com/gridsome/gridsome-starter-blog/blob/master/gridsome.config.js
The gridsome repo for source-filesystem has some docs to help: https://github.com/gridsome/gridsome/tree/master/packages/source-filesystem
Docs imported here in case the link breaks in the future (but the link is likely to be more up to date).
#gridsome/source-filesystem
Transform files into content that can be fetched with GraphQL in your components.
Install
yarn add #gridsome/source-filesystem
npm install #gridsome/source-filesystem
Usage
module.exports = {
plugins: [
{
use: '#gridsome/source-filesystem',
options: {
path: 'blog/**/*.md',
typeName: 'BlogPost',
route: '/blog/:year/:month/:day/:slug'
}
}
]
}
A filesystem source will also require a transformer in order to parse the files. The example above is looking for a set of Markdown files, so in order to let Gridsome understand the content of the files, you must install #gridsome/transformer-remark as a dev dependency in your project. Gridsome will automatically transform the files for you as long as a transformer that supports your files is found in your package.json.
Options
path
Type: string required
Where to look for files. Should be a glob path.
typeName
Type: string
Default: 'FileNode'
The GraphQL type and template name. A .vue file in src/templates must match the typeName to have a template for it.
route
Type: string
Define a dynamic route if your source is able to have a certain pathname structure. This will generate a single route for all nodes from this source. Possible path params are year, month, day, slug or any custom field value. If omitted, a route for each file will be generated based on their path and filename. Read more about route params.
refs
Type: object
Define fields that will have a reference to another node. The referenced typeName is expected to exist. But a content type can also be created autmatically if you set create: true. Read more about references.
{
refs: {
// Reference to existing authors by id.
author: 'Author',
// Create a Tag content type and its nodes automatically.
tags: {
typeName: 'Tag',
route: '/tag/:id',
create: true
}
}
}
index
Type: Array
Default: ['index']
Define which files to consider as index files. These files will not have their filename appear in its route path and will become the main index.html file of the directory. Make sure there is only one possible index file per directory if multiple index names are defined.
It is possible to reuse schema definitions with $ref. Is there a similar method for reusing string values, like the requestTemplates for Amazon's API Gateway extensions?
I've tried these methods, but both produce errors (I am not very familiar with YAML)
requestTemplates:
$ref: "#/definitions/MappingTemplate"
definitions:
MappingTemplate:
type: "object"
properties:
application/json: "the template"
and
requestTemplates:
application/json:
$ref: "#/definitions/MappingTemplate"
definitions:
MappingTemplate: "the template"
How can I use a $ref for requestTemplates?
References are currently supported for model schemas only. However, this should be possible with a local modification to upgrade the Swagger parser version in the pom.xml file.
Yes, references are supported in many parts of the swagger definition. If you look at the specification, you will see that references are allowed for path items, parameters, model definitions, etc. And each of those can be relative (in the same file) or absolute (into different http locations).