Comments (9)
A long overdue update on this issue!
Having a formal API definition is certainly a good thing. For us, as a Google team, the gRPC service definition is it. While our API is accessible via gRPC and HTTP, it's actually a single implementation under the hood, with the latter transcoded to and from the former. The API documentation is also generated from the same definition. This is how we ensure it all stays in sync.
Additionally providing an OpenAPI definition for the HTTP API would be nice, but since OpenAPI is not part of our setup, we'd need to have a reliable way to generate it from the gRPC service definition, including regenerating it when needed, and be confident that it's correct and wonβt drift over time. We did experiment with this, using protoc-gen-openapi, but unfortunately found that it did not generate correct output.
Fwiw, we have just updated the published gRPC service definition to include HTTP annotations, which define how gRPC methods are mapped to URLs. This means that it's now possible for anyone to generate HTTP client code from the gRPC service definition alone.
from deps.dev.
Happy to help review / collaborate. Thanks.
from deps.dev.
Mind sharing that work somewhere?
(Updated March 28, 2024 for v3 with "ossFuzz" now in response object for GetProject.)
from deps.dev.
metoo!
from deps.dev.
Thanks for the feature request. Can I ask about the intended use cases? Is it so that API client code can be auto-generated?
from deps.dev.
Partly, mainly for ease of consuming / validating the documentation. I run the Apis.guru OpenAPI directory. We could also convert from a Google discovery format file.
from deps.dev.
OAS can be used for various purposes, including:
- interactive documentation purposes: it can be rendered by UIs using a standard presentation format (e.g. se editor.swagger.io)
- client code generation
- data model validation
- catalogs.
Thanks for asking, R.
from deps.dev.
Please allow me to provide some justification for this request.
I just spent an afternoon manually converting https://docs.deps.dev/api/ to an OpenAPI definition. I was typing the whole thing by hand using Swagger Editor. This was very tedious, especially coding all the JSON Schema type definitions. The document became ~625 lines when done, also including the descriptions for each operation, parameter, and JSON Schema type. I am also not sure I got the "format" right on everything. Things that are a "number" I assume are probably "type: integer" and "format: int32" but this is just my guess. Additionally, some strings are URLs where I initially used "format: uri" but I found that the "links" returned in GetVersion sometimes fail to parse as such.
In my case, I was doing this for my own client code generation. This also simplifies stubbing out or mocking response objects when writing unit tests. There is a bit of tooling already available for OpenAPI and JSON Schema. So, I do not really need a special client library for an API when all I really need is an OpenAPI definition that describes the API.
from deps.dev.
I just spent an afternoon manually converting https://docs.deps.dev/api/ to an OpenAPI definition.
Mind sharing that work somewhere? Thanks in advance!
from deps.dev.
Related Issues (20)
- Dependent information storage
- LLM Dependency chatbot HOT 1
- GetRequirements API call does not return version in case of maven HOT 2
- Details for non-standard licenses HOT 3
- Add input examples / OpenAPI spec HOT 2
- Support `GetDependencies` to consider "context" information
- Latest version is not available fot nuget/Grpc.Core
- how to get the checksum information or some type of hash value of the package through the API HOT 1
- Unresolved dependency tree in go HOT 1
- The maven component query return data is missing the publishedAt field. HOT 1
- license ids do not always correspond to the official SPDX list HOT 2
- Commercial use of deps.dev HOT 1
- Compatibility v3 - v3alpha HOT 2
- Missing version for Go package github.com/cncf/xds/go
- Missing Go package github.com/docker/cli
- Missing version for Go package github.com/opencontainers/image-spec
- Support Go standard library package
- Missing version for Go package github.com/asaskevich/govalidator
- Frequent missing publishedAt element for versions where default = true HOT 1
- Python (PyPi) version numbers padded with '.0' HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. πππ
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google β€οΈ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from deps.dev.