Apiary Blueprint Docs: Unable to disable/hide schema

[foxx]

If you add attributes to a request, Apiary docs will automatically generate and output a schema. This is not always desired, and although you can replace schema with {}, there is no way to remove it completely. It would be nice to have the ability to optionally disable schema from being shown (perhaps if schema is empty? Currently if it's empty, it just outputs the generated schema from attributes)

[pksunkara]

Thanks for the suggestion. I was thinking the same and will message my colleagues about this.

[jeremytm]

:+1:

[pascalbaljet]

+1

[bjorkblom]

+1

[svvitale]

+1

[mapb]

+1

[dzemidzv]

+1

[eon]

+1

[mcanaves]

+1

[szimin18]

+1

[jeremytm]

@pksunkara any idea when this will be done? It seems like something that should be fixed before disabling legacy. It's the only issue that still remains for us before I'd be happy calling our documentation 1.0

[paraskakis]

Hi Jeremy,

It's something we have in the backlog, for the short term (i.e a few weeks). Unfortunately I can't promise you an exact date, but we'll announce it here. Is it very urgent for you?

Thanks,

Emmanuel

[jeremytm]

It won't stop someone from using our API, but it does make things bloated and more complicated than it needs to be for new users. Thanks for the update.

[gigafied]

If we can get this in by Nov 15th that would be swell :)

[BernieN]

+1

[paraskakis]

The plan is to collapse the schema in the documentation so it's not visible by default. You would be able to expand it to see it. We thought this is more flexible than having say a switch in Settings that turns it off completely. This is coming up on our next sprint so four weeks is the ETA.

[jeremytm]

Thanks @paraskakis, sounds good :)

If it could be placed somewhere other than in-between the attributes and response-body sections that would be ideal. It's just that where it appears now, it can be confusing to people who have no use for schemas.

[BernieN]

+1 for jeremytm's proposal

[claravanstaden]

I had a look at our docs now and this seems completed. Thanks!!

[pksunkara]

Thanks guys! :smile:

[jeremytm]

Yep, the implementation is perfect! Though now we have lost the attributes section :'(

[claravanstaden]

@jeremytm My attributes still show?

[jeremytm]

I've done some investigating. The new bug seems to only be affecting Attributes by way of Data Structures.

See the official Apiary Data Structures example.

For example, under the "Create a coupon" interactive area, we should see the Coupon Base data structure attributes listed as general attributes, and we should see the Coupons data structure attributes listed under the response. We no longer see either of these lists.

All of our attributes sections rely on Data Structures. Are these examples not being tested before each release?

[zdne]

Hey @jeremytm, thanks for pointing the regression issue out. I believe it has been just fixed and the Data Structures are now being rendered as before.

[zdne]

For the record: At Apiary, we have added the button to show and hide JSON schema in the rendered documentation. The schemas are hidden by default. Example:

[BernieN]

Like it. Thanks for that!