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.
Related
I'm currently looking into using our swagger-file that's mainly used for documentation to be used to generate client side SDKs.
I have noticed that our swagger file (that's in swagger 2.0 json format) contains references to defentitions like this:
"$ref":"#/definitions/My%20Awesome%20Object"
When I generate C# SDK, this translates to code that looks something like this:
ApiResponse<My20Awesome20Object>
Removing the %20 from the swagger file solves this issue, but talking to the web backend guys, they say that it's in there as it won't validate otherwise, and I can't find the refernce, but I remember that I found a reference in the swagger-codegen pages that states that the $ref field should be URI encoded, so it seems to be correct.
My current plan is to do a simple script that just strips out the %20 to generate proper references to classes. But that feels like a ugly workaround. Do you have any suggestion how to solve this in a nicer way that is complient to the standard while getting proper code?
Cheers,
Markus
$ref values are URIs. %20 is there because the schema names in the definitions section contain spaces, like so:
"definitions": {
"My Awesome Object": { // <--- $ref: "#/definitions/My%20Awesome%20Object"
"type": "object",
...
}
}
Some tools have problems with handling non-alphanumeric characters in schema names; this includes spaces, < >, « » and the like. Maybe this was why OpenAPI 3.0 restricted valid component names to A-Z a-z 0-9 - . _.
The best fix is to both remove %20 from the $refs AND remove spaces from the schema names in the definitions section. This way the schema names will be forward-compatible with OpenAPI 3.0 if/when you migrate to a newer OpenAPI version.
I have an OpenAPI 3.0 spec and I want to generate a PDF out of it so that it can be given to the end users.
Currently, tools like swagger-spec-to-pdf or swagger2markup only support Swagger 2.0 but not OpenAPI 3.0. Is it possible to generate a PDF from an OpenAPI 3.0 spec without converting it to Swagger 2.0?
A possible solution is to convert your OpenAPI 3.0 definition to an HTML doc, then use a browser's "Save to PDF" feature to convert HTML to PDF.
Follow these steps:
Go to https://editor.swagger.io.
Paste your OpenAPI 3.0 YAML/JSON definition.
Select Generate Client > html.
Download & unzip the file.
Open the index.html page in a browser, e.g. Chrome.
Select File > Print, change the Destination to Save as PDF, and save the page.
I just found RapiPDF which is able to generate PDF from OpenAPI 3.0 definition.
But it still isn't an ideal tool I'm looking for. I found these limitations so far:
No CLI, runs only in browser. So I can't use it in an automate pipeline.
Callback is not supported
No example in generated document
You can use this site and post your OpenAPI 3.0 spec (in json) directly into it. It's the easiest way, I think and the generated PDF looks pretty.
The following 2 packages helped me generate a PDF from OpenAPI json file:
org.openapitools:openapi-generator-gradle-plugin:5.0.0-beta2
org.asciidoctor:asciidoctor-gradle-jvm-pdf:3.2.0
Apply the relevant Plugin classes and the rest is pretty straight-forward task configuration. This is my groovy plugin but it shouldn't be difficult to find the corresponding gradle DSL extensions should you need to.
project.plugins.apply OpenApiGeneratorPlugin
GenerateTask adoc = project.tasks.withType(GenerateTask).iterator().next()
adoc.with {
it.input = swagger.outputDir.path + '/' + swagger.outputFileName + '.json'
it.generatorName.set 'asciidoc'
it.outputDir.set swagger.outputDir.path
// Leaving the below option empty can cause rendering issues
it.configOptions.putAll([
'infoUrl' : 'https://example.com',
'infoEmail': 'inbox#example.com',
])
}
project.plugins.apply AsciidoctorJPdfPlugin
project.tasks.withType(AsciidoctorPdfTask).iterator().next().with {
it.sourceDir = adoc.outputDir
it.outputDir = it.sourceDir
}
Let me know if there are questions about (or syntax errors in) this snippet.
DocBaker for OpenAPI: https://curvednebula.com/docbaker/
I'm the developer of the tool.
The easiest and nicest solution I found it is just using the usual https://editor.swagger.io/. Once you are happy with the generated outcome (on the right), just drag the central cursor on the left (to cover your source code) in order to visualise only the final documentation. Then if you use Chrome (similarly for Firefox), just (right button in the screen or from menu) choose "Print" and for "Destination" select "Save As PDF".
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.
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.