Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Repo info
Activity
    Mike Ralphson
    @MikeRalphson
    Just a heads up that we're now looking at adding our first OAS 3.0.x definitions to the directory. To distinguish them, the filenames will be openapi.yaml/openapi.json but everything else should be the same. At the moment there is no plan to downconvert these definitions to OAS 2.0 - please let me know if either of these considerations are likely to be a problem for you.
    Stefan Junker
    @steveeJ
    @MikeRalphson I've had some trouble with the downconverting when I experimented with it. AFAICT the MIME-types on a method are lost, i.e. don't translate to produces/consumes
    Mike Ralphson
    @MikeRalphson
    Good to know. Maybe we can start a to do list issue on api-spec-converter? At the moment the downconverter moves things around OK, but doesn't do all the necessary conversions to eg parameters and schemas.
    Stefan Junker
    @steveeJ
    Sounds good. is it this project? https://github.com/LucyBot-Inc/api-spec-converter
    Mike Ralphson
    @MikeRalphson
    Yep, that's the one.
    Stefan Junker
    @steveeJ
    I've filed an issue about this specific case
    Mike Ralphson
    @MikeRalphson
    Great, thanks.
    Stefan Junker
    @steveeJ
    FYI, yesterday I gave a talk to dive into this topic as part of an interview process. I'm quite intrigued by this problem space and can see some interesting tasks to work on: https://steveej.github.io/slides/zhaw-techtalk-0/#36 feel free to take a look from the beginning and start discussing with me, pointing me to things, or both
    Mike Ralphson
    @MikeRalphson
    That's a really good overview of where OpenAPI sits now and where its going. My only nitpick is that OAS 3.0.0 was released in 2017. You may be interested in the 3.1 roadmap issue on the OAS repository OAI/OpenAPI-Specification#1466
    Stefan Junker
    @steveeJ
    @MikeRalphson fixed, thanks :-)
    Stefan Junker
    @steveeJ
    hey, are there any projects that provide tooling or libraries for transforming arbitrary API descriptions which are written in JSON to OpenAPI?
    Mike Ralphson
    @MikeRalphson
    I don't know of anything specific, but you could use something like https://github.com/ColinEberhardt/json-transforms to massage the input JSON, then, if needed, one of the OAS libraries (see openapi.tools) to create the final OpenAPI definition. If you find something, it would be useful to share it, so it can be used for APIs-guru/openapi-directory#188
    Stefan Junker
    @steveeJ
    thanks for the links Mike. so I get your suggestion is to write it in JS?
    cloudcheckr.com provides an endpoint that exposes the known endpoints in JSON format. the linked file is a cache of it in YAML form
    unfortunately it lacks result information
    Mike Ralphson
    @MikeRalphson
    Other languages are (I believe) available. :smile: There are some good JSON transform tools available in Java I think. If you can find a nice DSL to OpenAPI tool you like, it looks like piping the YAML through that would be quite easy. There's only really the parameter information there, and you're going to have to default quite a lot of the OpenAPI boilerplate.
    Mike Ralphson
    @MikeRalphson
    You might have more luck using the HTML API reference here http://support.cloudcheckr.com/cloudcheckr-api-userguide/cloudcheckr-api-reference-guide/ and using https://github.com/bobby-brennan/scrape-to-swagger if you're happy with regexes and CSS selectors.
    Stefan Junker
    @steveeJ
    @MikeRalphson It's unclear, as I don't know the documentation process at cloudcheckr. the endpoints endpoint might be more accurate in regards to currency
    Stefan Junker
    @steveeJ
    @MikeRalphson I'm having a really hard time getting into the correct instrumentation of scrape-to-swagger :-D it's not straight forward without deep knowledge of JS and CSS
    Mike Ralphson
    @MikeRalphson
    All I have for you to go on is the existing examples in the config directory.
    Stefan Junker
    @steveeJ
    Do you have a suggestion for debugging the cheerio selectors?
    the firefox web console doesn't seem to support things like :contains, but I'd like to fully comprehend the examples
    Stefan Junker
    @steveeJ
    @MikeRalphson it seems that the openapi-codegen has not attracted much attention during the last few months. I'm about to spend some time on this topic again and am wondering which project to contribute to. I've found https://github.com/OpenAPITools/openapi-generator which has gained some momentum
    Mike Ralphson
    @MikeRalphson
    As I said to someone else recently, it comes down to whether you prefer a dsl driven or code driven approach, and nodejs vs java, and how much community support you want. Between swagger-codegen and openapi-generator I think it's too early to tell, but the main difference is between the larger breaking changes in sc and more continuity with og.
    Stefan Junker
    @steveeJ
    would you mind to elaborate on dsl driven vs code driven?
    Stefan Junker
    @steveeJ
    what is the completeness state of the parser? I'm willing to dig all the way into the templating and configuration, but I would be thrown off if the parser wouldn't deliver all of the specs elements
    in particular I'm interested in generating Go and Rust server and client code which supports http and apiKey security schemes
    Mike Ralphson
    @MikeRalphson
    Openapi-codegen uses a domain specific language (config file driven approach) while swagger codegen and openapi-generator subclass the model generation code for each language.
    Stefan Junker
    @steveeJ
    ah, you see the config file as a DSL, makes sense
    Mike Ralphson
    @MikeRalphson
    Openapi-codegen uses a validator, but not a separate parser as such. It converts all inputs into oas3 and works directly off that as the base model.
    Completeness can only really be measured by working configs /languages, but it should quickly tend towards 100%
    Stefan Junker
    @steveeJ
    I find the config file approach appealing
    it allows for replacing the parser implementation
    if one wanted that
    Mike Ralphson
    @MikeRalphson
    Yes, it has that benefit. I can't say how much attention it's going to get as it was initially only a hackathon proof-of-concept.
    Stefan Junker
    @steveeJ
    Can you point me to the config input parameters which would be used for the security definitions?
    I have no new experience in javascript since looking at this project a couple months ago :D
    Stefan Junker
    @steveeJ
    @MikeRalphson hey, is it possible to use the command line version of swagger2openapi for the same validation method as used on the online editor? for some reason a spec passes the CLI but fails the online validator
    Stefan Junker
    @steveeJ
    I found https://github.com/wework/speccy which is very helpful at finding errors and it also providers some useful lint rules
    Mike Ralphson
    @MikeRalphson
    Speccy is based on swagger2openapi's validator and linter. You can use the testRunner harness in swagger2openapi to validate and/or lint OAS documents. I'm not sure which online editor you're referring to though.
    Stefan Junker
    @steveeJ
    the one found under wizards @ https://mermade.github.io/openapi-gui
    that one wasn't very helpful when debugging null values in contactsx, terms of services, etc., which were automatically stored by the web-ui
    we have found some UX issues with the web-ui which we'll report the next few days :-) probably not much work to fix but very helpful when done
    Mike Ralphson
    @MikeRalphson
    @/all I'm thinking of migrating all the APIs in the collection which do not originate in Swagger/OpenAPI format to OpenAPI 3.x instead of Swagger 2.0 - for example this would affect all the Google and Amazon AWS APIs. Timescale for this would be around May this year. Would this cause problems for anyone?
    Sergey Tihon
    @sergey-tihon

    @MikeRalphson what will you do with component names in V3? I heard that [ & ] are not allowed in V3 component names but was used in V2.

    For example gettyimages uses these symbols in component names $ref: '#/definitions/GettyImages.Models.Search.SearchResults[GettyImages.Models.Search.ImageSearchItem]'
    As I understand Swashbuckle serialize .NET generic parameter types this way

    Mike Ralphson
    @MikeRalphson
    If this is an OpenAPI v2 definition, as above I won't be converting it anyway. More generally, will be replacing with underscores and suffixing with a digit if necessary.
    Mike Ralphson
    @MikeRalphson
    If anyone depends on the current path fragment hack for the AWS APIs, or has thoughts generally on the accuracy of those APIs, please take a look at APIs-guru/aws2openapi#11