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?
Related
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"
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.
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).
I am trying to generate python client from a swagger yaml file. It works fine, except that the response models are all snake cased(words sep. by underscores) instead of camel cased. I provided the camel cased versions like this:
definitions:
serviceResponse:
type: object
properties:
serviceResponseInternal:
type: object
The generated code has a ServiceResponse object which has an internal field service_response_internal. I would like it to respect the convention and just have serviceResponseInternal instead of underscored seperated names. How do I achieve this?
Assuming you're using Swagger Codegen, you can customize the toVarName in the Python code generator:
https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/PythonClientCodegen.java#L180
Can you elaborate on why you don't want to go with snake case for model properties (which should conform to Python style guide)?
UPDATE: On May 2018, about 50 top contributors and template creators of Swagger Codegen decided to fork Swagger Codegen to maintain a community-driven version called OpenAPI Generator. Please refer to the Q&A for more information.