I presently have
openapi: 3.1.0
info:
title: My API
version:
$ref: package.json#/version
description: |
practically the same content as README.md
Is there a way with JSON Pointers to embed text rather than JSON object? Something along the lines of
openapi: 3.1.0
info:
title: My API
version:
$ref: package.json#/version
description: |
$ref: README.md
Actually I was close and it did work. I didn't expect it to
openapi: 3.1.0
info:
title:
$ref: package.json#/description
version:
$ref: package.json#/version
description:
$ref: README.md
So now I basically avoided repeating myself for the title, version and the description.
Related
Is it possible to reference OpenAPI operation description from an external file?
Here is my sample code. I want to keep the description "This API is used to get user details" in a separate file and use it here like a variable or template or as a reference. Is there any way to do this?
get:
tags:
- User
summary: Get user details
description: This API is used to get user details
operationId: updateUser
parameters:
- name: userid
in: path
description: The id that needs to be pulled
required: true
schema:
type: string
If you use Redocly CLI to bundle, then you can put it in a separate file like this:
get:
tags:
- User
summary: Get user details
description:
$ref: ./updateUser-description.md
operationId: updateUser
parameters:
- name: userid
in: path
description: The id that needs to be pulled
required: true
schema:
type: string
Then, in a separate file named updateUser-description.md (note, you could change the name too):
This API is used to get user details
Then, when you run the bundle command it resolves the $ref and replaces the description with the contents in that corresponding Markdown file.
npx #redocly/cli bundle my-openapi.yaml
I'm trying to put the getBaseDir function from PHP in my OpenAPI YAML file to get the absolute path, but I don't know how to do it.
responses:
'200':
description: successful Operation
content:
application/json:
schema:
$ref: 'var/www/docroot/www/app/code/local/Project/Myproject/OpenAPI/components/schemas/test.yaml'
I have a springboot project in which I have developed an api with OpenApi in yml format and autogenerated the classes with openapi-generator-maven-plugin. The yml is as follows:
openapi: 3.0.2
info:
version: 0.0.1-SNAPSHOT
title: Example API
servers:
- description: Localhost
url: 'http://localhost:{port}/my-first-api'
variables:
port:
default: '8080'
tags:
- name: Example
paths:
/api/v1/examples:
get:
summary: Get examples
operationId: getExamples
description: Obtain a list of available examples.
tags:
- Example
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Example'
components:
schemas:
Example:
title: Example
type: object
properties:
description:
type: string
check:
type: boolean
example:
description: 'Example'
check: true
As you can see, I have defined that the local base path is:
http://localhost:8080/my-first-api
And later for the only available endpoint that is added:
/api/v1/examples
Therefore, I expected that once the artifact was started locally, I could consume the endpoint from this URL:
http://localhost:8080/my-first-api/api/v1/examples
But my surprise is that it doesn't work, this URL is not found. But if it finds the following:
http://localhost:8080/api/v1/examples
As you can see, it accesses without the "my-first-api" part of the path, but I need this part of the path to be there too... What could be happening?
Thanks!
In my tests, it worked just fine. The my-path part got changed, matching the spec changes.
#RequestMapping("${project.name.base-path:/my-path}")
But as you can see, spring would allow you to override this base URL using the project.name.base-path property. (The actual property name is probably different for you)
So, my suggestion would be:
Check if the annotation on the generated Controller changes at all.
If it does, check if the property is overridden at some point.
Check if you are setting spring's own base URL with the property server.servlet.context-path
I have installed the jekyll-compose gem to streamline creating pages, posts etc. In the documentation. I have it working (i.e using the CLI commands I am able to generate, drafts, posts and pages).
However when I generate a post for example, I want it to have certain variables in the front matter. There is functionality mentioned in the ReadMe of Jekyll Compose that says you can set front matter defaults for posts and for drafts.
I have followed the instructions by adding the required lines in the config.yaml of my site, however posts and drafts that I generate using jekyll-compose do not generate with the variables I want.
Jekyll-compose states that if you want default front matter variables you need add something like this to your _config.yaml:
jekyll_compose:
default_front_matter:
drafts:
description:
image:
category:
tags:
posts:
description:
image:
category:
tags:
published: false
sitemap: false
I have tried both their default config above and also my own below
jekyll_compose:
default_front_matter:
drafts:
main_img_url:
author_name:
categories:
description:
posts:
main_img_url:
author_name:
categories:
description:
But neither work when I generate a new post or draft. There are no error messages which makes it difficult to debug.
Originally my Jekyll version was at 3.7.0, I thought it might be an problem of a Jekyll version being too old. However this problem persisted when I updated Jekyll to 3.8.6.
It also does not work when I put default values for my custom variables, i.e:
jekyll_compose:
default_front_matter:
drafts:
main_img_url: "https://images-we-got-pop.imgix.net/website/blog/pop-logo-small.png"
author_name: "Me"
categories: "general"
description: "Description"
posts:
main_img_url: "https://images-we-got-pop.imgix.net/website/blog/pop-logo-small.png"
author_name: "Me"
categories: "general"
description: "Description"
My _config file looks like this:
title: Title
email: your-email#domain.com
description: > # this means to ignore newlines until "baseurl:"
Write an awesome description for your new site here. You can edit this
line in _config.yml. It will appear in your document head meta (for
Google search results) and in your feed.xml site description.
baseurl: "" # the subpath of your site, e.g. /blog
url: "" # the base hostname & protocol for your site, e.g. http://example.com
twitter_username: name
github_username: name
# Build settings
markdown: kramdown
theme: minima
plugins:
- jekyll-feed
- jekyll-paginate-v2
exclude:
- Gemfile
- Gemfile.lock
- Makefile
- README.md
permalink: /pages/:year/:month/:day/:title/
jekyll_compose:
default_front_matter:
drafts:
main_img_url:
author_name:
categories:
description:
posts:
main_img_url:
author_name:
categories:
description:
future: true
pagination:
enabled: true
sort_reverse: true
trail:
before: 1
after: 1
and my Gemfile looks like this:
source "https://rubygems.org"
ruby RUBY_VERSION
gem "jekyll", "3.8.6"
# This is the default theme for new Jekyll sites. You may change this to anything you like.
gem "minima", "~> 2.0"
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
# gem "github-pages", group: :jekyll_plugins
# If you have any plugins, put them here!
group :jekyll_plugins do
gem "jekyll-feed", "~> 0.6"
gem "jekyll-paginate-v2", "~> 1.9"
gem 'jekyll-compose', "~> 0.11"
end
I am expecting my custom front matter to appear in my newly generated posts:
---
title: this-is-a-new-post
date: 2019-10-09 10:45 +0100
main_img_url:
author_name:
categories:
description:
---
But I only get the standard ones that get created with the post/draft, eg:
---
title: this-is-a-new-post
date: 2019-10-09 10:45 +0100
---
Any ideas??
Ok I managed to fix this myself after seeing the syntax for the custom variables was different on GH compared to what I found when digging into the jekyll-compose post creation methods on rubydoc.info.
Basically there was PR that changed the syntax merged in to master but not yet released, hence why I was having difficulty getting it to work
The current syntax as of the latest release:
jekyll_compose:
draft_default_front_matter:
description:
image:
category:
tags:
post_default_front_matter:
description:
image:
category:
tags:
published: false
sitemap: false
Compared to the config structure illustrated in the Readme and on master in the jekyll-compose repo, but had't been released at the time when I looked at the docs:
jekyll_compose:
default_front_matter:
drafts:
description:
image:
category:
tags:
posts:
description:
image:
category:
tags:
published: false
sitemap: false
I have a bunch of concourse pipeline files that look like the following:
---
resources:
- name: example
type: git
source:
uri: git#github.internal.me.com:me/example.git
branch: {{tracking_branch}}
private_key: {{ssh_key}}
paths:
- code/src/do/teams/sampleapp
params:
depth: 1
- name: deploy-image
type: docker-image
source:
repository: {{docker_image_url}}
And I want to parse them in ruby to perform a bunch of transformations (like validating them and updating some keys if they are missing).
Problem is, whenever I try to load and them dump them back to files the pieces that have {{something}} become:
branch:
? tracking_branch:
:
private_key:
? ssh_key:
:
Why is it doing this and is there any way I can configure the parser not to do this? Just leave these variables as they are?
To avoid conflict with YAML's internal syntax you need to quote your values:
---
resources:
- name: example
type: git
source:
uri: git#github.internal.me.com:me/example.git
branch: '{{tracking_branch}}'
private_key: '{{ssh_key}}'
paths:
- code/src/do/teams/sampleapp
params:
depth: 1
This sort of thing comes up in Ansible configuration files all the time for similar reasons.
The { and } characters are used in Yaml for flow mappings (i.e. hashes). If you don’t provide a value for a mapping entry you get nil.
So in the case of branch: {{tracking_branch}}, since there are two pairs of braces, you get a hash with a key branch and value (in Ruby) of
{{"tracking_branch"=>nil}=>nil}
When this is dumped back out to Yaml you get the somewhat awwkward and verbose:
branch:
? tracking_branch:
:
The solution is simply to quote the value:
branch: "{{tracking_branch}}"
Completely forgot that concourse now offers ((var-name)) for templating, just switched to that instead of {{var-name}} at the pipelines and the YAML parser is now happy!