I spend the last few weeks trying to find an appropriate SDL for my project but have otherwise no experience in creating APIs.<p>In my opinion, API specs should probably be generated from code and its documentation, and not the reverse. This is because it is the code and not the spec which is subject to most change and only the endpoint interfaces&#x2F;signatures can be generated. API specifications could also be more easily transformed by middleware (e.g. when renaming endpoints, combining APIs) if they were machine generated.<p>As was described above, only few people are acquainted with service description languages, and deeper changes in their semantics over time or the choice of an alternative would require a manual rewrite. Also, some SDLs seem to impose their own higher level ontologies and name spaces, which is another major obstacle to usage for simple systems.