Support for Attributes - Githubissues

kalmanb commented 8 years ago

Add the ability to extend apidoc by adding custom attributes/metadata to elements.

The intention is to have a way for supporting non-core attributes on elements within specs. This would allow for additional data to be passed to code generators and/or documentation processors. For example attributes could be used to define additional validation or language specific implementation details while not poluting the apidoc spec.

Discussion so far has been in PR's #385 #386 #389

Direction is to add attributes as a core element in the UI. Once defined in the UI they can be used with specifications.

mbryzek commented 8 years ago

Just checking in to see how things are going?

kalmanb commented 8 years ago

Hey, been working on a bunch of generators, play app and kafka. Will get back to this next week.

mbryzek commented 8 years ago

FYI - we also need the attribute support to finish up work for go clients. Have been working to add attributes - overview is here:

https://github.com/mbryzek/apidoc/blob/local_attributes/attribute.md

If you have a minute, would love your feedback / thoughts - I've tried to structure the work so that it would incrementally move us towards supporting what you need.

kalmanb commented 8 years ago

I'm getting close a PR for the simple attribute support. That's where attributes can be defined within the apidoc web ui. They're simple and it's only the definition not the value currently. Based off the previous PR.

A couple of interesting requirements that you have. Do you need attrs at the org level or can they be defined at the app level instead? It would involve duplication but also flexibility. In your example each app would define: attribute -> go_base -> github.com/flowcommerce/apidoc/ You could also have if you needed: attribute -> go_base -> github.com/flowcommerce/apidoc-beta/ eg flexible This would be easy to do by allowing attributes the top level (app level) of the apidoc specs. Currently they're just at the model, field etc.

I have been thinking about a better way to do validation of attributes when a spec is uploaded to the web app. We're using attrs for our code generation at the moment and often get caught out by a typo. It only gets picked up when the generators run and because some attrs are optional it can take us some time to spot the issue. The ability for a generator to specify which api spec it uses for attrs would be great.

Here's our current spec. It's supports additional validation, additional scala types, scala class extn, kafka etc. http://apidoc.me/movio/apidoc-generator-attributes/0.1.0-SNAPSHOT And actual generators: https://github.com/movio/apidoc-generator Currently running internal until we get attrs support in http://apidoc.me

Thoughts?

mbryzek commented 8 years ago

FYI - first version of attribute support in apidoc is now live - see apidoc.me/doc/attributes

kalmanb commented 8 years ago

Looks great. Will give it a whirl and let you know. Doing a talk at http://scaladownunder.org/ on apidoc in 30 mins :)

mbryzek commented 8 years ago

This looks amazing! Nice work

For org level settings - the use case we have is for a new generator we added for golang. Essentially we need a way to implement imports that plays nicely with the go ecosystem. What we came up with is really a mapping rule that essentially says

If you import from apidoc "io.flow" namespace, turn that into github.com/flowcommerce/apidoc as the golang base import

This really is a global organization setting as it's a process we setup once for our company.

What I was thinking is maybe apidoc supports basic inheritance:

if an attribute value is specified in the application, use that
if an attrbiute value is specified in the org, use that

I think this is still reasonably simple and enables some really nice use cases (including our need for golang).

I also ran into the validation error for attributes - on HEAD of apidoc - you'll see that each generator actually has an attributes method - so it should be trivial to validate the attribute names now (but I have not done any work with the application attribute values themselves knowing you were working in that area).

Mike

On Thu, Feb 18, 2016 at 8:51 PM, Kalman notifications@github.com wrote:

Looks great. Will give it a whirl and let you know. Doing a talk at http://scaladownunder.org/ on apidoc in 30 mins :)

— Reply to this email directly or view it on GitHub https://github.com/mbryzek/apidoc/issues/391#issuecomment-186009105.

mbryzek commented 8 years ago

Also - if useful for your talk - we just kicked off work to build native javascript libraries as well - so that will be live in the coming weeks!

On Thu, Feb 18, 2016 at 9:36 PM, Michael Bryzek mike@flow.io wrote:

This looks amazing! Nice work

For org level settings - the use case we have is for a new generator we added for golang. Essentially we need a way to implement imports that plays nicely with the go ecosystem. What we came up with is really a mapping rule that essentially says

If you import from apidoc "io.flow" namespace, turn that into github.com/flowcommerce/apidoc as the golang base import

This really is a global organization setting as it's a process we setup once for our company.

What I was thinking is maybe apidoc supports basic inheritance:

if an attribute value is specified in the application, use that

if an attrbiute value is specified in the org, use that

I think this is still reasonably simple and enables some really nice use cases (including our need for golang).

I also ran into the validation error for attributes - on HEAD of apidoc - you'll see that each generator actually has an attributes method - so it should be trivial to validate the attribute names now (but I have not done any work with the application attribute values themselves knowing you were working in that area).

Mike

On Thu, Feb 18, 2016 at 8:51 PM, Kalman notifications@github.com wrote:

Looks great. Will give it a whirl and let you know. Doing a talk at http://scaladownunder.org/ on apidoc in 30 mins :)

— Reply to this email directly or view it on GitHub https://github.com/mbryzek/apidoc/issues/391#issuecomment-186009105.

kalmanb commented 8 years ago

It's been crazy running the conference. All sorted now. I'll get the app attributes finished off.

Had a look at the org attributes - looks good. I'm already starting to think up other uses for it. Not sure that we'll need inheritance yet, can work around it if needed - would be a nice to have though.

I was actually going to do talk on the second day with a code demo for creating a generator microservice and use javascript as the simple example. Javascript client generator would be neat.

BTW, one of the biggest push backs I'm getting regarding apidoc from the team is the look and feel. I've got one of our designers to have a look at the UI - hope you don't mind.

mbryzek commented 8 years ago

I would love help w/ the UI and UX! hopefully the www app is laid out pretty smoothly - If there's anything I can do to help, pls just ping

On Mon, Feb 22, 2016 at 3:11 AM, Kalman notifications@github.com wrote:

It's been crazy running the conference. All sorted now. I'll get the app attributes finished off.

Had a look at the org attributes - looks good. I'm already starting to think up other uses for it. Not sure that we'll need inheritance yet, can work around it if needed - would be a nice to have though.

I was actually going to do talk on the second day with a code demo for creating a generator microservice and use javascript as the simple example. Javascript client generator would be neat.

BTW, one of the biggest push backs I'm getting regarding apidoc from the team is the look and feel. I've got one of our designers to have a look at the UI - hope you don't mind.

— Reply to this email directly or view it on GitHub https://github.com/mbryzek/apidoc/issues/391#issuecomment-187063539.

kalmanb commented 8 years ago

Hey Mike, I've been pondering this a bit. Currently we're running a local branch that has attribute support in the spec but no UI support. Our attrs are all optional so we can't add validation to api on upload, we could only validate that the attribute exists (in the UI). The main benefit is that there is documentation within the apidoc UI itself. Because of the minimal tie in, I'm wondering if we leave the attributes adhoc in the spec's instead of referencing the UI.

What do you think?

mbryzek commented 8 years ago

Couple thoughts:

Personally, I think it's important to be able to list the attributes that each code generator supports. For example, at http://apidoc.me/generators/ you can see that the go_1_5_client can use the go_import_mappings attribute
That said, there is no reason why we can't add this later

So one path forward - we can take the work you've done and merge into apidoc master - and then iterate from there. And if there is a clean pull request then I'm super excited to review and get it in - and during that process may even be able to do the work to pull up the documentation all the way to the attributes page.

WDYT?

On Tue, Mar 1, 2016 at 10:49 PM, Kalman notifications@github.com wrote:

Hey Mike, I've been pondering this a bit. Currently we're running a local branch that has attribute support in the spec but no UI support. Our attrs are all optional so we can't add validation to api on upload, we could only validate that the attribute exists (in the UI). The main benefit is that there is documentation within the apidoc UI itself. Because of the minimal tie in, I'm wondering if we leave the attributes adhoc in the spec's instead of referencing the UI.

What do you think?

— Reply to this email directly or view it on GitHub https://github.com/mbryzek/apidoc/issues/391#issuecomment-191043759.

kalmanb commented 8 years ago

Good points, I agree that is a good use case for UI attrs. Let's push forward, I'll get a PR ready.

apicollective / apibuilder

Support for Attributes #391