Generate curl samples for requests

[RomanHotsiy]

[darklynx]

:+1:

[cayter]

Can we actually render Request Sample when there is x-code-samples specified? I have an use case to add my own written SDK code sample.

[RomanHotsiy]

@cayter yes, this is actually a bug. Thanks for reporting. I've opened a separate issue: https://github.com/Rebilly/ReDoc/issues/93

[cayter]

Ahh ok thanks.

[adamschnaare]

Just wondering if there was any plans to move on this? This feature would be excellent. I'm not too familiar with the code base, but this seems a good workaround solution before coding up a full API console integration.

[jgabriels]

I have a fully working code generator: https://github.com/Direct-Freight/df-api-docs/blob/master/scripts/generate-code-samples.js It's called during the build: https://github.com/Direct-Freight/df-api-docs/blob/master/scripts/build.js You can see what the final results looks like here: http://apidocs.directfreight.com/#tag/boards I created a pull request here: https://github.com/Rebilly/generator-openapi-repo/pull/18 but haven't tested it on any third party definitions.

[ornicar]

That looks amazing, jgabriel. Can't wait to be able to use it!

[jgabriels]

@ornicar: It's really only a single file:
https://github.com/Direct-Freight/df-api-docs/blob/master/scripts/generate-code-samples.js You should be able to just download that one file and run it in your project's root directory. I would love for someone to run it and let me know if it works for their project.

[ornicar]

Thanks, I tried to use it but it doesn't seem to like my YAML file. I'll try something tomorrow.

[raderio]

Is it possible to grab the code from swagger-ui?

[bottleboy]

How do you generate the x-code-samples code snippets in the yaml/json file? Is there any way to do it automatically?

[jgabriels]

How do you generate the x-code-samples code snippets in the yaml/json file? Is there any way to do it automatically?

This is what I use: https://github.com/Direct-Freight/df-api-docs/blob/master/scripts/generate-code-samples.js

It automatically generates code samples for a bunch of different languages.

You can see what it looks like here: http://apidocs.directfreight.com/#tag/boards

[bottleboy]

How do you generate the x-code-samples code snippets in the yaml/json file? Is there any way to do it automatically?

This is what I use: https://github.com/Direct-Freight/df-api-docs/blob/master/scripts/generate-code-samples.js

It automatically generates code samples for a bunch of different languages.

You can see what it looks like here: http://apidocs.directfreight.com/#tag/boards

Thank you @jgabriels , but I see that swagger-snippet only works with version 2.0 of Open Api and I have a 3.0 file, is that correct?

[jgabriels]

Thank you @jgabriels , but I see that swagger-snippet only works with version 2.0 of Open Api and I have a 3.0 file, is that correct?

I believe that may be correct. One workaround might be to use one of the many 3.0 to 2.0 converters to make a 2.0 version of your api and run the code generator on that.

[raderio]

Any updates on this? Maybe the implementation can be borrowed from Swagger UI?

[hawy31]

Any updates?

[SebastianStehle]

I think this feature is overrated. A simple solution would be to add a "Open in Postman" link. I am not sure if this is possible.

[darklynx]

@SebastianStehle or simply import YAML to Insomnia, BUT it does not replace the mentioned functionality from this issue at all!

People, like me, may not have Postman around them. If you are in console on the server where you should send the request from, it might take you quite a number of actions before you tunnel the request from your PC to the server and use your favorite UI to send requests through it. And last, but not least: nothing beats the simplicity of sending a request using curl regardless whether you are on Linux, BSD, Mac or Windows, just paste the query into console and press "Enter".

[Cloudmersive]

It cannot be understated how important Curl support is for API documentation

[lucie-docs]

Any progress on this issue? This feature is essential yet still missing from ReDoc...

[rishabh12j]

please guide i am looking for the exact same but unable to get any lead is the feature still missing from ReDoc...... @RomanHotsiy @adamaltman can you please guide us if possible please.Thanks in Advance

[paxter]

I tried swagger-codegen, openapi-generator and now landed here. It's the best choice in my opinion, but a CURL example support is the one feature I'm missing here. : /

[rohit-gohri]

https://github.com/cdwv/oas3-api-snippet-enricher works for some cases. It looks for defaults/examples in a particular place so if you have them differently the snippets won't be very helpful.

[hungtsou]

This package worked for me I hope it helps someone. openapi-snippet

[rsby]

Using the openapi-snippet mentioned above by hungtsou, the following (rough) script will add the x-code-samples as expected by Redoc:

// USAGE:  node add_api_snippets.js my_api.yml > my_api_with_snippets.yml

const OpenAPISnippet = require('openapi-snippet')
const yaml = require('js-yaml');
const fs = require('fs');

const openApi = yaml.load(fs.readFileSync(process.argv.slice(2)[0], 'utf8'));
const targets = ['node_fetch', 'python_requests', 'shell_curl'];

try {
    Object.keys(openApi.paths).forEach(path => {
        Object.keys(openApi.paths[path]).forEach(method => {
            const snippets = OpenAPISnippet.getEndpointSnippets(openApi, path, method, targets);
            const samples = []
            openApi.paths[path][method]['x-code-samples'] = samples;
            snippets.snippets.forEach(snippet => {
                samples.push({
                    lang: snippet.title.split(' ')[0],
                    source: snippet.content
                })
            })
        })
    })
    console.log(yaml.dump(openApi))
} catch (err) {
    console.log(err)
}

[BoKKeR]

Here is an improved version of the script above, change x-codeSamples to x-code-samples if you are running old redoc:

const OpenAPISnippet = require('openapi-snippet')

const addRequestSamples = (swaggerJson) => {
  const swagger = JSON.parse(JSON.stringify(swaggerJson));
  const targets = ['shell_curl'];
  const httpRequestMethods = ['get', 'head', 'post', 'put', 'delete', 'options', 'trace', 'patch'];

  for (const singlePath in swagger.paths) {
    Object.keys(swagger.paths[singlePath])
      .filter((method) => httpRequestMethods.some((supportedMethod) => supportedMethod === method))
      .forEach((method) => {
        try {
          const snippets = OpenAPISnippet.getEndpointSnippets(swagger, singlePath, method, targets);
          const samples = [];

          snippets.snippets.forEach((snippet) => {
            samples.push({
              lang: snippet.title.split(' ')[0],
              source: snippet.content,
            });
          });
          swagger.paths[singlePath][method]['x-codeSamples'] = samples;
        } catch (error) {
          console.log(error);
        }
      });
  }

  return swagger;
};

[braco]

^^ the above answers combined

const openAPISnippet = require('openapi-snippet');
const yaml = require('js-yaml');
const fs = require('fs');

const targets = ['node_fetch', 'python_requests', 'shell_curl'];
const httpRequestMethods = ['get', 'head', 'post', 'put', 'delete', 'options', 'trace', 'patch'];

const addRequestSamples = (swaggerJson) => {
  const swagger = JSON.parse(JSON.stringify(swaggerJson));

  for (const singlePath in swagger.paths) {
    Object.keys(swagger.paths[singlePath])
      .filter((method) => httpRequestMethods.some((supportedMethod) => supportedMethod === method))
      .forEach((method) => {
        try {
          const snippets = openAPISnippet.getEndpointSnippets(
            swagger,
            singlePath,
            method,
            targets,
          );
          const samples = [];

          snippets.snippets.forEach((snippet) => {
            samples.push({
              lang: snippet.title.split(' ')[0],
              source: snippet.content,
            });
          });
          swagger.paths[singlePath][method]['x-codeSamples'] = samples;
        } catch (error) {
          console.log(error);
        }
      });
  }

  return swagger;
};

const args = process.argv.slice(2);
const openApi = yaml.load(fs.readFileSync(args[0], 'utf8'));

console.log(yaml.dump(addRequestSamples(openApi)));