Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Repo info
Activity
    Robert Brennan
    @rbren
    Are we able to down-convert new 3.0 definitions to 2.0? It would be a bit annoying to have specs available only in 3.0, but it's better than not having it
    Mike Ralphson
    @MikeRalphson
    Understood. Converting 2.0 to 3.0 is nearly lossless (but not trivial), but I don't know of any 3.0 to 2.0 downconverters. I imagine as more people migrate to 3.0 they will be doing so because they want to use features which aren't supported by 2.0. Still, if someone was to sponsor the work, I'd have a go.... :smile:
    Mike Ralphson
    @MikeRalphson
    As pointed out by @darosh Microsoft have completely re-organised their Azure API collection. This means there is a very large update coming, where serviceNames for existing APIs will change. Please let me know if this is a problem for any integration you have. I propose to defer this update by one week, and implement it from 2017-12-11, but you can preview the changes now in the 'azure' branch.
    Robert Brennan
    @rbren
    @MikeRalphson is there a list anywhere of the Azure name changes? Or a way to get that info?
    Mike Ralphson
    @MikeRalphson
    The source of truth would be the renames in the source Azure repo. There have been at least two. I could look at generating a cross reference. What format would you need?
    Robert Brennan
    @rbren
    anything I could ingest in JavaScript that would map from new_name -> old_name would be super helpful
    Mike Ralphson
    @MikeRalphson
    I'll see what I can do.
    Robert Brennan
    @rbren
    thanks!
    Robert Brennan
    @rbren
    @MikeRalphson, any update here? If you can point me in the right direction I'm happy to take a crack at it.
    Mike Ralphson
    @MikeRalphson
    @bobby-brennan not yet. I think the approach would be to get a list of renames from the azure sdk repo history, and then compare those to the origin entries (then and now) in the directory repo. I can get you the relevant commit ids...
    Robert Brennan
    @rbren
    sounds good. Looks like a few AWS API names changed as well?
    those I can probably just match up manually
    Mike Ralphson
    @MikeRalphson
    Yes, some filenames changed to ensure they reflected the serviceName property rather than the source AWS filename.
    Sergey Tihon
    @sergey-tihon

    I found schemas like https://api.apis.guru/v2/specs/azure.com/automation-softwareUpdateConfiguration/2017-05-15-preview/swagger.json that contains reference to definition in relative document "$ref":"./definitions.json#/definitions/softwareUpdateConfigurationCollectionItem” but I cannot find definitions.json near the schema file https://github.com/APIs-guru/openapi-directory/tree/master/APIs/azure.com/automation-softwareUpdateConfiguration/2017-05-15-preview

    I there any way to resolve such references? // cc @IvanGoncharov

    Mike Ralphson
    @MikeRalphson
    @sergey-tihon yes, sway, the resolution and validation library we use, seems to be missing some refs in the Azure definitions. I'm trying to find a fix.
    Sergey Tihon
    @sergey-tihon
    @MikeRalphson thank you, should I create Github issue for this or you already have one?
    Mike Ralphson
    @MikeRalphson
    Yes we already have issue #351
    Mike Ralphson
    @MikeRalphson
    We've launched an Open Collective fundraiser to help cover the hosting costs of the openapi-directory. If you find the directory useful, or integrate with it, please consider donating. Thank you. https://opencollective.com/openapi-directory
    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%