search

apiaryio / api-elements

API Elements is a structure for describing APIs and the complex data structures used within them.
http://apielements.org/
MIT License
28 stars 10 forks source link

feat: support "host" resources #62

Closed marcofriso closed 4 years ago

marcofriso commented 4 years ago

Update the specification at to include "Server Element" structure described by OAS 3 format (https://swagger.io/docs/specification/api-host-and-base-path/).

As reported on Swagger website:

"In OpenAPI 3.0, you use the servers array to specify one or more base URLs for your API. servers replaces the host, basePath and schemes keywords used in OpenAPI 2.0. Each server has an url and an optional Markdown-formatted description."

In OAS 3.0 a simple server looks like this:

servers:
  - url: '{protocol}://api.example.com'
    description: 'Description of the server'
    variables:
      protocol:
        enum:
          - http
          - https
        default: https

In Api Elements a server should contain a href and optionally hrefVariables. A simple OAS3 server would map to a server element like this:

element: server
meta:
  description: Production
attributes:
  href: https://example.com/

For more information about the design please check the following link → https://github.com/apiaryio/api-elements/issues/53#issuecomment-444589557

UPDATE → after talk to @tjanc I am going to remove server object and introduce hosts classification under "Resource" and "Category"

marcofriso commented 4 years ago

I am not completely sure about this one...

marcofriso commented 4 years ago

In the last commit server object has been replaced by classification hosts under resource and category elements.

marcofriso commented 4 years ago

I see also some of the internal links have to be changed as they don't work