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.
Related
The value side of attributes in HTML were very unreadable, too dark, making it especially hard to disseminate between class names in HTML, when using the dark theme on VS Code.
How do I change it to make reading more comfortable?
p.s. My "Tags" are very limited due to rep, but I'm so sure others have this question.
Here is how to accomplish this particular task.
Introducing [me to] a very useful tool: Inspect Editor Tokens and Scopes
Put cursor in, in this case, a quoted value string.
CNTL + SHIFT + P (open command palette).
Find "Developer: Inspect Editor Tokens and Scopes"
Note the textmate scope(s).
Use property: "editor.tokenColorCustomizations" → "textMateRules" to add new rule.
While I'm doing this directly on values in the JSON of settings - and changing quotes there at a high level, this also works with inheritance, so string.quoted.double.html would override the example shown in this screenshot (which applies to ALL double quoted strings), when editing HTML files. I find this useful for making my lint rules standout too.
I am trying to automate conversion of a GitHub Pages site to LateX in order to produce a PDF. The Kramdown parser used by GHP understands the following definition list syntax:
term1
: definition1
term2
: definition 2
so definition lists formatted this way in Markdown show up correctly on GHP. However, Pandoc's --from=gfm flag does not understand this syntax, since it's not officially part of the GFM spec. I have tried:
--from=gfm+definition_lists
but the definition_lists extension appears to be ignored with from=gfm. I have also tried:
--from=markdown+definition_lists+attribute_headers
but that doesn't appear to understand Kramdown-style attribute headers (which I need in order to specify section IDs, because legacy text). Is there a way to get Pandoc to deliver the definition list behavior of Jekyll+Kramdown and attribute headers? Thanks.
Try -f markdown_github+definition_lists. markdown_github is pandoc's legacy gfm parser. gfm is the new one, which just wraps the C library and so doesn't accept all the extensions.
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.
I am using Swagger-php and Swagger-UI and it all works just fine but for one annoyance. The UI that Swagger-UI creates has the expected click-to-expand sections for my API routes, but the title of each one appears to be the JSON file generated and not any name I can give it. After the title, the description is the one I give in my annotation, but the title I seem to have no control over.
So if I have routes that begin with a resourcePath of /foo, and a description that says "Foo API Functions," the UI looks like:
foo.json : Foo API Functions
I don't want "foo.json" I'd much rather specify what this says. Like just "Foo" or even "Foo Functions" and then change my description to something more meaningful like, "This is where you find the foo functions."
Am I missing which annotation to use for this?
If you manually edit the api-docs.json file. You can replace the .json with .{format} and all will display correctly and function correctly. Not sure why the .{format} is not inserted by default. Slightly annoying.
I too ran into this problem, but I couldn't find anything on either theswagger-php or swagger-ui github pages mentioning this. So, I wrote a short build script (assuming a Unix-like OS) as a work around, which will first build all the docs using swagger.phar and then run sed to do an inline string replace on the problematic string. Here is what I did below:
#!/bin/bash
# write API documentation from "src" directory to the "docs" directory
/usr/bin/php swagger.phar src -o docs
# replace instances of "json" with "{format}" to fix swagger-php formatting issue
sed -i -e 's/json/{format}/g' docs/api-docs.json
Fixed in swagger-php 0.9.1
I don't know why swagger-ui strips out ".{format}" but not ".json"
The .{format} was not inserted by default because it might be confusing. It suggests the presence of different formats and swagger-php only supports the json format.
EDIT: For those that say: do not do this, I most respectfully point out that 1. this is something that is allowed by javascript and, more importantly, 2. this is something that I need to do for pedagogical reasons.
I would like to "validate" my javascript code with jslint (or jshint ... or something equivalent) but, unfortunately, it fails due to the presence of non-ascii characters in identifiers. Does someone know of a validator like jslint which accepts non-ascii characters in identifiers?
I know of a partial workaround, which is to use something like
this["andré"]
instead of
this.andré
but do not know of an equivalent workaround for something like
var andré = ...
Version 1.0.0 of JSHint will add support for unicode characters in identifiers. Currently this is available as a release candidate which you can download on GitHub. From the JSHint blog:
This version adds support for Unicode identifiers!
var π = 3.1415;