search

Azure / api-management-developer-portal

Developer portal provided by the Azure API Management service.
MIT License
478 stars 306 forks source link

Developer Portal API Documentation Style #2305

Open plalea opened 8 months ago

plalea commented 8 months ago

Many modern API documenations, including Microsoft's own documentation, have a clean and user-friendly look, often resembling a readme.com style that is both visually appealing and user-centric. How can we achieve a similar look and feel for our API documentation within the Developer Portal? Are there any guidelines, templates or best practices that can help us align API documentation with the standard style? We are specifically interested in implementing the design and layout characteristics commonly found in well-structured API documentation.

malincrist commented 8 months ago

Hello @plalea , thanks for reaching out. We are currently working on implementing the addition of documentation to APIs and products in markdown format, which seems to be what you are looking for. It will be released sometime in the near future, but we do not have a clear ETA yet.

chadbert commented 8 months ago

How soon will this be ready? The old developer portal is being shutdown next week and migrating our API documentation pages is a huge pain to do in the WYSIWYG system of the new portal. If I can just convert our HTML pages to markdown and use those, that would be fantastic. If this isn't going to be ready by then, can we keep the old portal open until this feature is available?