I am using a swagger plugin in my visual studio code.Using the plugin I have created a spec (openapi: 3.0.1) and externalized the common schemas and examples. I added them in to the folders "schemas" and "examples" and I am referring to these as below and it works fine.
requestBody:
content:
application/json:
schema:
"$ref": "./schemas/sampleRequestformat.yml"
example:
"$ref": "./examples/sampleRequest.json"
How can I externalize schemas and examples in swagger hub UI . Is there any way i can group examples and schemas for a project othe rthan defining it in components section.
Thanks in advance
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?
If we open the swagger editor website https://editor.swagger.io/ it has one default swagger example. The first several lines are
swagger: "2.0"
info:
description: "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters."
version: "1.0.0"
Generally we know there are two types of swagger file. YAML and json. The default of course is not JSON. And the default is very similar to YAML but it is not. Because in the menu and we can choose “convert to YAML” and it will convert to
swagger: '2.0'
info:
description: >-
This is a sample server Petstore server. You can find out more about
Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net,
#swagger](http://swagger.io/irc/). For this sample, you can use the api
key `special-key` to test the authorization filters.
version: 1.0.0
we can see some " change to ' and some " are removed.
I am wondering what is name of this default type and where is definition of that format? What is difference of it with YAML? In this website https://swagger.io/docs/specification/2-0/basic-structure/ it has YAML definition and but I can not find any defination of the default format.
Thanks
These YAML examples are equivalent, they just use different ways to format strings. YAML strings can use both single and double quotes, and in some cases (like version: 1.0.0) quotes can be omitted. There are also several ways to split long strings (such as description in your example) into multiple lines and format multi-line strings.
My organization has a lot of APIs for different projects. I need an OpenAPI implementation that allows me to create a standalone portal that contains all these APIs (more like a repository) for all our products.
Is there an OpenAPI that supports this?
Another option would be: to be able to merge several instances to a single OpenAPI instance.
There are several ways to implement API catalogs.
Swagger UI (open-source)
Swagger UI 3.0.19+ can display multiple API definitions using the url parameter.
// index.html
const ui = SwaggerUIBundle({
dom_id: '#swagger-ui',
urls: [
{name: "petstore", url: "http://petstore.swagger.io/v2/swagger.json"},
{name: "instagram", url: "https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.yaml"}
],
"urls.primaryName": "petstore", // default spec
...
Result:
Since Swagger UI is open source, you can customize its layout and look&feel as your needs dictate.
SwaggerHub (commercial)
SwaggerHub provides API catalog hosting for teams & organizations, either in the cloud or on premises. SwaggerHub also supports API design, collaboration, code generation and workflow integrations among other things.
Disclosure: I work for the company that makes SwaggerHub.
To do that, a great solution is to use SwaggerHub as indicated. However, this tool is not free for private API.
I had the same need, so, to help community in OpenAPI design, I wrote a new tool named "OpenAPI Dev Tool" (in github).
With OpenAPI Dev Tool, we can deploy several documentations (for several use contexts) for Swagger UI / Redoc with hot reload feature, like an SwaggerHub.
It is really easy to use.
Each API is indicated in a configuration file :
{
"folder": "./specs", // Root folder where the specifications are stored
"specs": [ // Array of specifications (several specifications can be exposed)
{ // First specification file
"file": "/petstore.yaml", // Relative path of the specification main file (from "folder" parameter). It has to be an OpenAPI file in YAML or JSON.
"context": { // Object used for template generation (see Template usage chapter below)
...
}
},
{ // Second specification file
"file": "/petstore2.yaml"
...
}
]
}
Then, you can serve the whole API just by hitting npx openapi-dev-tool serve
Open your browser with http://localhost:3000 et voilà :)
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).
Having a master JSON file
{"swaggerVersion":"1.2",
"apiVersion":"1.0",
"apis":[{"path":"/api1"},{"path":"/api2"},{"path":"/api3"},{"path":"/api4"}]}
and JSON files for each of the 4 APIs, which working well with the Swagger library each.
But when I tried to place it all into one JSON file like
{"swaggerVersion":"1.2",
"apiVersion":"1.0",
"apis":[{<api1 json file contents>},{<api2 json file contents>},{<api3 json file contents>},{<api4 json file contents>}]}
it didn't work.
What is proper way to do merge several Swagger v. 1.2 files into a single file?
According to the Swagger 1.2 Specification you just cannot do that.
The "master" JSON file (as you called it) is the Resource Listing of a Swagger API, which just contains an "inventory of the available resources".
The "apis" property of this JSON document is expected be an array of Resource Objects with a specific structure:
{
"path": "/pets",
"description": "Operations about pets."
}
Quoting the API Declaration section of the spec:
The API Declaration provides information about an API exposed on a resource. There should be one file per Resource described. The file MUST be served in the URL described by the path field.
Take a look at the demo application to view all service documentations at a single location: https://github.com/varghgeorge/microservices-single-swagger
Repo shows how to create a springboot application which will serve as a single place for all your springfox/swagger documentations.
Swagger documentation from different services/locations can be configured in this server using yaml config. Details are on the github location.