REST API documentation via OpenAPI

[danielmarschall]

There should be an OpenAPI documentation that is automatically generated from the restApiInfo() methods of the plugins. I don't have the time to study the OpenAPI specification, so maybe someone can help me with this task? Thank you very much!

[wehowski]

Hello Daniel, as I know you are not a big friend of libraries/dependencies. Although I suggest to take a look at https://github.com/cebe/php-openapi#writing-api-description-files Maybe this helps?

I m not sure if I can promise any help, have to read the spec first ...

[MarieSnajderova]

Hello, Do you still working on that project and need API documentation? I would like to try working with API documentation. Maybe it will help and could contribute to your project. Marie

[danielmarschall]

Hello, thank you very much for that offer! Yes, I still need help with the documentation. The current documentation is written in plain text, but it would be good if it could follow the OpenAPI specification (which is a bit too complex for me at the moment).

[MarieSnajderova]

Could you please send me the documentation in plain text. I will try to write API specification based on that.

[danielmarschall]

Hello,

the field list is like this:

Please note that the fields are not actually described (I can do that later). My main issue is the OpenAPI data structure. If you could do this, then I can easily edit the explanations of the fields later. Thank you very much.

• Receive
  • GET https://www.example.com/oidplus/rest/v1/objects/[ns]:[id]
  • Input parameters
    • None
  • Output parameters
    • status (<0 is error, >=0 is success)
    • status_bits
    • error (if an error occurred)
    • ra_email
    • comment
    • iris (for OID only)
    • asn1ids (for OID only)
    • confidential
    • title
    • description
    • children
    • created
    • updated
• Re-Create
  • PUT https://www.example.com/oidplus/rest/v1/objects/[ns]:[id]
  • Input parameters
    • ra_email (optional)
    • comment (optional)
    • iris (optional)
    • asn1ids (optional)
    • confidential (optional)
    • title (optional)
    • description (optional)
  • Output parameters
    • status (<0 is error, >=0 is success)
    • status_bits
    • error (if an error occurred)
    • inserted_id (if it was created)
• Create
  • POST https://www.example.com/oidplus/rest/v1/objects/[ns]:[id]
  • Input parameters
    • ra_email (optional)
    • comment (optional)
    • iris (optional)
    • asn1ids (optional)
    • confidential (optional)
    • title (optional)
    • description (optional)
  • Output parameters
    • status (<0 is error, >=0 is success)
    • status_bits
    • error (if an error occurred)
    • inserted_id
• Update
  • PATCH https://www.example.com/oidplus/rest/v1/objects/[ns]:[id]
  • Input parameters
    • ra_email (optional)
    • comment (optional)
    • iris (optional)
    • asn1ids (optional)
    • confidential (optional)
    • title (optional)
    • description (optional)
  • Output parameters
    • status (<0 is error, >=0 is success)
    • status_bits
    • error (if an error occurred)
• Remove
  • DELETE https://www.example.com/oidplus/rest/v1/objects/[ns]:[id]
  • Input parameters
    • None
  • Output parameters
    • status (<0 is error, >=0 is success)
    • status_bits
    • error (if an error occurred)

[Azuris2]

Hi Marie,

Are you in the midst of working on this?

Hi Daniel,

Just to clarify - would the response for the endpoints be a JSON/XML object containing the output parameters as key value pairs?

[danielmarschall]

Hello, yes, it is a REST interface with the result being a JSON object. The "value" can be an array, not just a string.