opticdev / optic Goto Github PK

Hi Guys.

Maybe I am doing something wrong, but when I edit the descriptions of my endpoints the changes are kept in the browser session but never persisted to disk. So, next time I open the project they are gone.

However, if in the same browser session I edit descriptions of already recorded URLs and then I document a new URL and save it flushes everything.

I am doing something wrong?

If a process takes more than 25 seconds to start (the timeout for Optic checks) the Optic check will fail as it won't be able to reach anything on that port. This may be the intended behavior of a project (slow startup) but check will have no way to validate the configuration.

Workaround

If all other checks pass, bypass the check with api run <task> instead. The run command will work, though the target application will need to start before traffic can be meaningfully observed. If startup is slow, please wait for the application to be fully initialized and ready for traffic.

Reproduction

Reproduces 100% of the time on MacOS 10.15 though it's a timing issue, not an environment issue, and should generally reproduce.

Reproduction optic.yml tasks below to demonstrate:

optic.yml

tasks:
  sleepy:
    command: sleep 30 && nc -l $OPTIC_API_PORT # 30 second sleep will fail
    baseUrl: http://localhost:3001
  awake:
    command: sleep 5 && nc -l $OPTIC_API_PORT # 5 second sleep will work
    baseUrl: http://localhost:3001

api check awake

[optic] Testing task awake

Your command: sleep 5 && nc -l $OPTIC_API_PORT
  ✔ Starts a long running process (your API)
  ✔ On the host Optic assigns it $OPTIC_API_HOST (current: localhost)
  ✔ On the port Optic assigns it $OPTIC_API_PORT (current: 3399)

Given this inboundUrl: undefined
  ✔ Optic proxy is able to start its proxy here localhost:3001

[optic] All Passed! This task is setup properly. Nice work!

api run sleepy

[optic] Testing task sleepy

Your command: sleep 30 && nc -l $OPTIC_API_PORT
  ✔ Starts a long running process (your API)
  ✔ On the host Optic assigns it $OPTIC_API_HOST (current: localhost)
  ✖ On the port Optic assigns it $OPTIC_API_PORT (current: 3429)
    → Your command did not start the API on $OPTIC_API_PORT after 25 seconds

Given this inboundUrl: undefined
  ✔ Optic proxy is able to start its proxy here localhost:3001

[optic] Some checks failed. Steps to fix can be found here: useoptic.com/docs/check-fail

We want to keep the feedback we receive on the API Designer public, and easily accessible to the entire community. Let's treat this issue as a thread for general feedback -- if you have a feature request or bug report please open a separate issue. Thanks!

Try the designer out here https://design.seamlessapis.com

can't find the command api intercept , any other alternative for this. Like to record the requests from postman.

Thanks in advance

Hey Optic Devs,

I keep receiving errors when I run the "npm install optic-installer -g" command.
This seems to be the one that is stopping the installation:

Error: ENOENT: no such file or directory, chmod

It also returns errno -4058

If you have any ideas or need more info, let me know.

Thanks!

What has you interested in Seamless?

What are the biggest challenges in API workflows? Which would you like this project to address?

What do you think of the roadmap? Our current tooling?

Howdy!

After noticing the new update i deleted Optic and installed the new version as your docs specify, but i've got this error:

This are my system specs:
Linux debian 4.19.0-9-amd64 #1 SMP Debian 4.19.118-2+deb10u1 (2020-06-07) x86_64 GNU/Linux

And these are my development environment details:

~/Projects/node/api_rest_cruciclub_optic · (master±)
⟩ npm -v
6.14.6

~/Projects/node/api_rest_cruciclub_optic · (master±)
⟩ node -v
v13.11.0

~/Projects/node/api_rest_cruciclub_optic · (master±)
⟩ pm2 -v
4.4.0

Lastly, here are my project details, you can check them at this repo

{
  "name": "crucijuegos-api-rest",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "start": "npm run pm2 && pm2 flush && pm2 log api-rest",
    "pm2": "pm2 start pm2-env.config.js --only api-rest"
  },
  "dependencies": {
    "bcrypt": "^4.0.1",
    "cookie-parser": "^1.4.4",
    "cors": "^2.8.5",
    "debug": "~2.6.9",
    "ejs": "~2.5.7",
    "express": "~4.16.0",
    "helmet": "^3.15.1",
    "http-errors": "~1.6.2",
    "jsonwebtoken": "^8.5.0",
    "mercadopago": "^1.3.2",
    "morgan": "~1.9.0",
    "mysql2": "^1.6.5",
    "pm2": "^4.4.0",
    "sequelize": "^4.43.0",
    "twilio": "^3.48.0",
    "winston": "^3.2.1"
  }
}

@all-contributors please add @devdoshi for Core Development
@all-contributors please add @acunniffe for Core Development

So, i'm working on an API that will scale a lot over time, and when i was looking for a good OAs3 autodocumenting solution on SO, i stumbled with Optic.

I followed the install and setup guides and ended up with the next setup:

1. optic.yaml which initially had the suggested port: 4000, however i later changed it to port: 3300 since it was the one that Optic was trying to use, also take note on the command (more on that in 3.):
   

2. bin/www entry point, which differs from the examples in the guides, thus i tried different combinations with app and server objects:
   

3. And since this project is handled by PM2, note the npm run pm2 definition, it uses the PM2 Ecosystem Configuration File (see 4.):
   

4. Said file is just an autodocumented and easier to handle way to launch PM2 Processes, as far i understood Optic should end up intercepting/wrapping the app, which in time gets wrapped by PM2, however there might be a conflict around that matter:
   

These are the errors that i could not work around, no matter how i handle bin/www and optic.yaml:

I also tried just launching the api check start by using node app.js and node bin/www commands to completely avoid PM2, but the behavior remains.

I'm quite sure the problem is around 2....

I'm using node - express - typescript

After:

• installing optic
• typing api init in powershell in root directory of my API
• setting up all the options available on the page
• typing api start in powershell

I'm getting an error:

[optic] Optic needs more information about your API to continue.
This directory already has an optic.yml file.

Hi,

Is that possible to remove an api endpoint ?

Rgds

Hi, it's a little unclear what the contribution guidelines for the repo are. Are assigned Issues off-limits? Are can they still be worked on? Any commit message convention? Thank you!

Is your feature request related to a problem? Please describe.
I'm trying to create concepts that make it easier to follow our REST conventions. I have a specific approach to pagination, hypermedia and a few other things that I often duplicate throughout our API.

Describe the solution you'd like
Ideally I could create a concept with a generic parameter ie InfiniteScroll[Users] or InfiniteScroll[Venues]. When I use that concept in a request I'd be asked to set the type of the parameter.

Describe alternatives you've considered
I could manually build a new shape each time, but that's harder to get other engineers to buy into.

Additional context
Usually I have an object like this {items: [array of type T], offset: int, limit: int}

While it would require a manual interface to designate them, the presence of a dictionary object in a schema would currently only show an ever-expanding set of data specific properties. Having the ability to document an object as having any valid properties or using the typescript interface [index: String]: String would allow for more accurate documentation and would keep potentially sensitive information out of docs.

Example:

report: {
	[index: String]: String
}
// vs
report: {
	personsName: string,
	unrelatedSportsScore: number
	...
}

or on inputs

{
	"name":"reportId",
	"reportSpecificInputs":{
		[index: String]: String
	}
}
// vs
{
	"name":"reportId",
	"reportSpecificInputs":{
		"billNumber": string
		// ... any number of properties that are only relevant to their specific ID
	}
}

Specifically for my use case, this it the reason I can't use Optic; with lots of business reporting, using dictionaries to keep JSON size smaller makes sense, but each report or specific dataset could contain nearly a hundred fields unique to it. Testing just a couple large dictionary containing routes could instantly render the documentation unmanageable.

Hello,

I am interested in using optic in order to generate open api for the existing endpoints.
I have an installation of my application in the cloud, and would like to run optic separately. The idea it that I do not use the port env variable inside my app, but rather tell optic which application (port, host) to proxy and then just use the optic host and generate traffic to it directly.

Not sure if it is possible at all, could not find any documentation for this.

Thanks a lot

Steps to reproduce:

1. run npm install optic-cli -g
2. run optic
   Got the error:

? Finish Install: Configure local Optic server. Yes
Installing local Optic server...
downloading and preparing JRE + Optic Server [====================================] 100% 0.0s
Optic server could not be installed.Smoketest failed.

Thanks for this tool. It does looks promising.

When adding a path in Document a New Request. If I entered a wrong path in 2. Add path to your API spec field and added it, there is no way to modify the path unless I close and restart again.

Maybe a back button would help here or some other way to edit that.

Upon installation, a log file is created in the local directory but is not automatically gitignored.

.optic-daemon.log could be added to .gitignore automatically.

Alternatively, it could be placed in .optic and gitignored there.

I am trying to follow the advice in #39

   start:
     command: npm run start
     baseUrl: http://localhost:3700
   publish:
     oas: |
       widdershins {{{OAS_PATH}}} -o /tmp/api.md
       shins --inline -o ../doc/index.html /tmp/api.md

But this doesn't work for me.

› Error: command publish not found

I can run these command from the command line, and I could create an npm script for them. I have tried a few combinations, including taking out the pipe after oas:, but nothing seems to work

well done guys for the tool

I am having the issue when sharing the UI optic link https://app.useoptic.com/shared/YHqi3ZW9 :

The request could not be satisfied.
The Lambda function associated with the CloudFront distribution is invalid or doesn't have the required permissions. We can't connect to the server for this app or website at this time. There might be too much traffic or a configuration error. Try again later, or contact the app or website owner.
If you provide content to customers through CloudFront, you can find steps to troubleshoot and help prevent this error by reviewing the CloudFront documentation.
Generated by cloudfront (CloudFront)
Request ID: qftDhSmMqe2d4utsDngf3cSQSDMJP-hrMysZkIqZzxKL5WfYzT0CQQ==```

can you help on this ?

Rgds

Integration with Azure Devops?

I think it would be nice to update gitbook with an "Api PUBLISH" entry
I understand we can add "publish oas" in the api.yml and create api doc.

that would be great to have this documented with examples.

Goal would be to create a flag that allows extensions to explicitly disable saving to disk when you register the connection. Should be a query parameter like /editors/atom?autorefresh=true

when I run :
# api spec

I got the following output :

  errno: -2,
  code: 'ENOENT',
  syscall: 'open',
  path: '/var/tmp/shaq/.api/sessions/interceptor-session.optic_session.json'
}

to make it work I have to open a second console with # api intercept

did I miss a config somewhere ?

Hi team,
I am a .NET developer and I am using Windows to work.
I have a suggestion for api init to give an option to ignore command/start.

name: MyAPIs
commands: // ignore this
  start: dotnet run --project ./WebApi/WebApi.csproj
proxy:
  target: 'http://localhost:51859' // assign development port ENV.OPTIC_API_PORT 
  port: '5005'

When I start my APIs by Visual Studio, IIS Express web server create "http://localhost:51859" so I don't need command/start.
And can I have ability to give development port for ENV.OPTIC_API_PORT instead of changing development port manually?

hi,

i try some your exemple in the doc.
If i got authetification or special header, how can i make it ?

thanks and great job 👍

It looks like older versions (v6 for example) had a command api intercept. Is something like this still around? My API has a mix of languages and not all of them use a framework you support, so operating at a proxy or nginx level would be fantastic for my team.

PS - I opened an issue in the docs repo, but that's probably the wrong place for this question.

Hi

I am trying to setup optic for a java project which uses spring boot and maven. But i am unable to start optic for my project. Following are the steps i have followed -

1. Run api init on project root which contains pom.xml

   Ankits-MacBook-Air:mposweb ankitrustagi$ api init
   /Users/ankitrustagi/Documents/GitHub/mposweb
   Is this your API's root directory? (yes/no): yes
   [optic] opening http://localhost:34444/specs/1/init
   Ankits-MacBook-Air:mposweb ankitrustagi$ 
   

After this i am taken to the "Welcome to Optic" page, which i try to setup like this -

After this, my optic.yml file looks like this -

  +name: myapp
  tasks:
    start:
      command: echo "./mvnw"
      baseUrl: http://localhost:8443
  ignoreRequests:
    - GET /favicon.ico
    - OPTIONS *

But this does not work, when i run api start it simply exits after echoing my run command

 Ankits-MacBook-Air:mposweb ankitrustagi$ api start
 [optic] Review the API Diff live at http://localhost:34444/specs/1/diff/939cce9a-1207-4bfa-8e79-fc81ef494e02
 ./mvnw
 Ankits-MacBook-Air:mposweb ankitrustagi$ 

Since my deployment command is ./mvnw, I tried tweaking the optic.yml file to -

  +name: myapp
  tasks:
    start:
      command: ./mvnw
      baseUrl: http://localhost:8443
  ignoreRequests:
    - GET /favicon.ico
    - OPTIONS *

But for some reason, when i run api start the tomcat server does get started but a few seconds later 2 java processes seem to get spawned on the same port 8443 and tomcat startup eventually fails. The error message says -

 ***************************
 APPLICATION FAILED TO START
 ***************************

 Description:
 Web server failed to start. Port 8443 was already in use.
 Action:
 Identify and stop the process that's listening on port 8443 or configure this application to listen on another port.

I confirmed that there are two un-identical java processes by running ps aux | grep java -

 Ankits-MacBook-Air:mposweb ankitrustagi$ ps aux | grep java
 ankitrustagi     84044 300.3  5.4  7947036 452500 s004  R+    9:01AM   0:20.08 /Library/Java/JavaVirtualMachines/jdk..... <omitted for brevity>
 ankitrustagi     84046   0.0  0.0  4277236    808 s002  S+    9:02AM   0:00.01 grep java
 ankitrustagi     84012   0.0 13.2  7943732 1108872 s004  S+    9:01AM   2:00.31 /Library/Java/JavaVirtualMachines/jdk1.8.0_211.jdk/Contents/Home/bin/java -classpath /Users/ankitrustagi/Documents/GitHub/mposweb/.mvn/wrapper/maven-wrapper.jar -Dmaven.home=/Users/ankitrustagi/Documents/GitHub -Dmaven.multiModuleProjectDirectory=/Users/ankitrustagi/Documents/GitHub/mposweb org.apache.maven.wrapper.MavenWrapperMain

The final setup page looks like -

Notice the following line in the attached image -

 WAITING FOR YOUR API TO RUN ON `$OPTIC_API_PORT` NULL

Why is $OPTIC_API_PORT set to NULL? Is there something incorrect with my setup steps? I noticed that spring/java isn't mentioned in the list of frameworks on the first setup page, does optic support spring/java projects?

Hi

I'm trying out optic for documenting my existing APIs. I could get it setup to capture my API requests which is great. I wanted to cleanly shut down the Optic Daemon when I'm not using it but could not find a way to shut it down cleanly.

Basically in my workflow I run
api run <task_name>

Go through my test cases and capture the APIs being used.
Ctrl-C the api run task to stop my app.

Look at the Optic dashboard to review the diffs and add/edit the API's captured

After this I still find that the following process keeps running on the system

/usr/bin/node /usr/lib/node_modules/@useoptic/cli/node_modules/@useoptic/cli-server/build/main

I would like to shut this down cleanly and be able to start it back up the next time I start testing, but could not find any way to do this.

When documenting my endpoints in Optic, I give them meaningful names like:

Then I run api generate:oas --yaml, and in the generated spec, I can only find:

paths:
 '/{apiVersion}/client_config':
  get:
   operationId: request_rkydO6Sol8

There's no trace of the readable name I gave it in Optic. This becomes a particular issue if I try to generate code, as it will use the operationId as method name. Is this a bug?

Hi,

1. I make "npm install @useoptic/cli -g"
2. api init
   I follow step by step the doc https://docs.useoptic.com/ but its produce error when type "api init"

Env
npm 6.13.7
@useoptic/cli/7.0.5 win32-x64 node-v13.6.0

project dependency :
"dependencies": {
"@types/express": "^4.17.2",
"@types/node": "^13.7.1",
"express": "^4.17.1"
}

import * as express from 'express';
// tslint:disable-next-line: no-duplicate-imports

const app = express();

app.get('/', (req: any, res: any) => { res.json({ test: 'Api is alive !' }); });
app.get('/Test', (req: any, res: any) => { res.json({ exTest: 'Expected this !' }); });

app.listen(3000, () => { console.log('My API is running...'); });

export default app;

When use api init its produce this:

    at Object.<anonymous> (C:/Users/Martin/AppData/Roaming/npm/node_modules/@useoptic/cli/node_modules/registry-js/dist/lib/registry.js:4:7)

There are other requirements for launching api init ?

Hi
My test failed and in the diff window, I accepted a response code 500
is it possible to edit the response options and accept only a response code 200
thanks

On the doc, for lisibility can you make on 'get started' some many gif for install optic on a server ?
(whatever project it is, just a pragmatical case ex for todolist)

when i asking 'Do you know what is optic ? see it' i would like of my partner will see quickly how Optic is great 🥇.

exemple see the readme how is beautifull here is enquirer package

thanks for the job what you done 👍

I'd like to serve the doc along with my API under the endpoint /doc but now for serving I need to run the api spec which is a node server that I have to host somehow.

Is it possible to generate html instead ?

Regards

I tried to follow the brew instructions
I got the following error:

brew install opticdev/optic/api
==> Tapping opticdev/optic
Cloning into '/usr/local/Homebrew/Library/Taps/opticdev/homebrew-optic'...
remote: Enumerating objects: 757484, done.
remote: Total 757484 (delta 0), reused 0 (delta 0), pack-reused 757484
Receiving objects: 100% (757484/757484), 303.19 MiB | 11.07 MiB/s, done.
Resolving deltas: 100% (502921/502921), done.
Tapped 1 formula (28 files, 323.4MB).
==> Installing api from opticdev/optic
==> Downloading https://homebrew.bintray.com/bottles/node-15.0.1.catalina.bottle.tar.gz
==> Downloading from https://d29vzk4ow07wi7.cloudfront.net/9cdf039763f006eef0cc0aaebb13bc8173f017d961ac41c30f26d45a23ecffe0?response-content-dispos
######################################################################## 100.0%
==> Downloading https://registry.npmjs.org/@useoptic/cli/-/cli-8.4.2.tgz

curl: (22) The requested URL returned error: 404
Error: Failed to download resource "api"
Download failed: https://registry.npmjs.org/@useoptic/cli/-/cli-8.4.2.tgz

Describe the bug
The Optic API session naming convention used today is not compatible with most versions of windows. Naming a file or directory

To Reproduce
Run API Start on Windows
Cancel API Start
Run API Spec
Error: ENOENT: no such file or directory, open 'D:/Learning/optic/server-example/.api/sessions/2019-09-09T09:40:31.725Z-2019-09-09T09:40:53.179Z.optic_session.json'

Expected behavior
API Sessions save and load properly.

OpenApi format has the 2 following entries :
"title": "Unnamed API",
"version": "1895"

Would be nice to be able to update it from the "api spec" ?
also, why is "share Api" not present in the "api spec" ?

Thanks.

While I have been testing this library, I have noticed that query parameters in the get requests are not being captured.

Installed Optic and tried running it on the demo code. It shows as connected to vscode but shows "No results found" no matter what file I open. My job security worries have been alleviated.

Hi Team,

Its very interesting project towards API docs and testing. Will optic supports python rest frameworks like fastapi, flask, etc..

Thanks you

I was trying to document api endpoints, I had some different instances of optic running from a few days ago and it kept crashing when I was going to apply the changes to diffs on while creating documentation for an api request.

Hello,

What i expected is :
When you make devops, you just test all things with command pipeline on travis like :
npm i && npm i -g mocha && npm test && cd ./things && ts-node file.ts

optic provide a command line for test all the doc ?

I am trying to define an API which has the following spec:
/api/addons/:addon_id - get addon info
/api/addons/timestamp - get addon database timestamp

Unless I'm missing something, Optic does not allow me to define the wildcard :addon_id but also have a static path timestamp - it marks them as the same endpoint and fails to resolve the response JSON conflicts, since the responses have nothing to do with each other - they're two completely separate endpoints. I am aware that this is not exactly a beautiful API spec, but it is unfortunately what I am working with. Any way to get this to work?

Hello,

It seems that in the openapi exported file is missing some fields.
When I try to generate an html using shins (see #39) I have some discrepancies like

• The name of the endpoint is some random id like request_xxxxxxx while I'd like to be the same title as in the api spec view

• generally speaking we miss a lot of user added info like descriptions and IMO it can be simple to add these and enrich the openapi file and thus all generated doc from it.

I am running Optic in proxy mode, and some of the endpoints fail with:

Failed to handle request: aborted

As far as I can tell, and this may be a coincidence, but these endpoints return a pretty large JSON response (7000 lines), and Optic seems to bail at that sight. is there any way to increase the maximum line limit?

• I downloaded optic from the useoptic.com website, and its not working in MAC

hi,

according to this post i made test optic on windows cause i have another issues on get started on optic, maybe is specificly due to windows env ... #61

there is new issue when i success to make 'api init' ...

I think something is broken, i make api start, it seem working well.

what you want test on windows ?