Re: [akka-user] Re: Swakka - a new extension to akka-http for Swagger/OpenApi

[Konrad “ktoso” Malawski]

Awesome, and +1 for the move to github (starred, watched) :-)

-- 
Cheers,
Konrad 'ktoso ' Malawski
Akka  @ Lightbend 

On February 21, 2018 at 18:03:10, Jeremy Townson (jeremy.town...@gmail.com)
wrote:

Thanks, Patrik. I have raised https://github.com/akka/akka-http/issues/1874.

One thing to note is that I have moved Swakka to github. The bitbucket link
earlier in this thread is now broken and correct link is
https://github.com/jtownson/swakka (also in the ticket).

I can make the documentation change if you provide a pointer to the right
section.

Regards,
Jeremy

On Friday, 16 February 2018 19:06:44 UTC, Patrik Nordwall wrote:
>
> Thanks for the update Jeremey. Is the availability of this already
> mentioned in akka-http documentation? Otherwise I think it would be worth
> adding that somewhere. Please open an issue and we can work out the details.
>
> regards,
> Patrik
> ons 31 jan. 2018 kl. 20:32 skrev Philippe Derome :
>
>> never mind, it's not needed, I had communication with Spark in mind and
>> that does not require to be in same process.
>>
>>
>> On Wednesday, January 31, 2018 at 12:45:53 PM UTC-5, Philippe Derome
>> wrote:
>>>
>>> Jeremy,
>>>
>>> do you have any intent to make this project available with Scala 2.11?
>>>
>>> Phil
>>>
>>>
>>> On Tuesday, January 30, 2018 at 5:21:52 PM UTC-5, Jeremy Townson wrote:

 Thanks for reporting this, Philippe. For anybody who experienced this
 problem, fixed in https://bitbucket.org/jtownson/swakka/commits/
 0f5cb77196ea83135f9ca7913f1f111f6b39f369. Please pull from master.

 Actually I am planning a move to github soon, because of their really
 good usage stats.

 On Tuesday, 30 January 2018 19:56:26 UTC, Philippe Derome wrote:
>
>
> I had issues with credentials w.r. sonatype and removed all references
> thereof in build.sbt and plugins.sbt and this temporarily resolved my
> issues. I am not interested in publishing artifacts to an external site 
> but
> perhaps you are.
>
>
> On Tuesday, January 30, 2018 at 10:08:06 AM UTC-5, Philippe Derome
> wrote:
>>
>> Would you consider migrating the project to github since you find it
>> more stable now? I am unable to make use of it from bitbucket due to some
>> sonatype_credentials file issue, which looks mysterious to me and would
>> like to give this a dev try today.
>>
>> Thanks,
>>
>> Phil
>>
>>
>> On Wednesday, January 24, 2018 at 5:18:59 PM UTC-5, Jeremy Townson
>> wrote:
>>>
>>> Hi Akka users,
>>>
>>> This is an update about Swakka, an addon for generating
>>> OpenApi/Swagger docs with Akka-Http. I introduced Swakka in August last
>>> year. Back then it was new, unstable and I recommended people not to 
>>> use it.
>>>
>>> Yesterday, I cut a v0.5 release. Whilst the library does not cover
>>> Swagger 100%, it does cover everything in the Swagger’s famous 
>>> PetstoreV2
>>> sample. Therefore it should document many real world APIs.
>>>
>>> If you are creating Akka-Http endpoints and have a need to document
>>> them, I recommend you check out the project at
>>> https://bitbucket.org/jtownson/swakka/. I hope it would help your
>>> project and I would be really interested to hear your feedback.
>>>
>>> Beyond toughening up the library for a 1.0 release, I am also
>>> starting to consider where to go next with the project. Thoughts in my 
>>> mind
>>> right now are
>>> — do something completely different
>>> — support for other documentation formats like Api Blueprint or RAML.
>>> — having a close look at Akka-Http’s routing DSL, to see if there is
>>> a refactor that would yield an AST. Now that Swakka can do doc 
>>> generation
>>> from its OpenApi case class, if it _were_ possible to generate an AST 
>>> from
>>> a Route structure, it might also be possible to map over that to 
>>> produce an
>>> instance of OpenApi. Akka-Http users would then have the choice of 
>>> either
>>> coding an OpenApi instance and getting Swakka to generate Routes, or 
>>> coding
>>> Routes and generating OpenApi. I’m not convinced this is any more than a
>>> dream and I do not feel I have either the knowledge or authority to go
>>> tinkering with one of the core abstractions in Akka-Http. But if this
>>> interests you, you are familiar with the Akka-Http codebase and want to
>>> take a punt as a pair, I’m game.
>>>
>>> All the best,
>>> Jeremy
>>>
>>> On Monday, 21 August 2017 10:54:44 UTC+1, Jeremy Townson wrote:

 Hi Akka Users,

 I would like to introduce *Swakka*, a library for adding
 Swagger/OpenApi doc generation to akka-http. https://bitbucket.
 org/jtownson/swakka.

 Like 

Re: [akka-user] Re: Swakka - a new extension to akka-http for Swagger/OpenApi

[Jeremy Townson]

Thanks, Patrik. I have raised https://github.com/akka/akka-http/issues/1874.

One thing to note is that I have moved Swakka to github. The bitbucket link 
earlier in this thread is now broken and correct link is 
https://github.com/jtownson/swakka (also in the ticket).

I can make the documentation change if you provide a pointer to the right 
section.

Regards,
Jeremy

On Friday, 16 February 2018 19:06:44 UTC, Patrik Nordwall wrote:
>
> Thanks for the update Jeremey. Is the availability of this already 
> mentioned in akka-http documentation? Otherwise I think it would be worth 
> adding that somewhere. Please open an issue and we can work out the details.
>
> regards,
> Patrik
> ons 31 jan. 2018 kl. 20:32 skrev Philippe Derome  >:
>
>> never mind, it's not needed, I had communication with Spark in mind and 
>> that does not require to be in same process.
>>
>>
>> On Wednesday, January 31, 2018 at 12:45:53 PM UTC-5, Philippe Derome 
>> wrote:
>>>
>>> Jeremy,
>>>
>>> do you have any intent to make this project available with Scala 2.11? 
>>>
>>> Phil
>>>
>>>
>>> On Tuesday, January 30, 2018 at 5:21:52 PM UTC-5, Jeremy Townson wrote:

 Thanks for reporting this, Philippe. For anybody who experienced this 
 problem, fixed in 
 https://bitbucket.org/jtownson/swakka/commits/0f5cb77196ea83135f9ca7913f1f111f6b39f369.
  
 Please pull from master.

 Actually I am planning a move to github soon, because of their really 
 good usage stats.

 On Tuesday, 30 January 2018 19:56:26 UTC, Philippe Derome wrote:
>
>
> I had issues with credentials w.r. sonatype and removed all references 
> thereof in build.sbt and plugins.sbt and this temporarily resolved my 
> issues. I am not interested in publishing artifacts to an external site 
> but 
> perhaps you are.
>
>
> On Tuesday, January 30, 2018 at 10:08:06 AM UTC-5, Philippe Derome 
> wrote:
>>
>> Would you consider migrating the project to github since you find it 
>> more stable now? I am unable to make use of it from bitbucket due to 
>> some 
>> sonatype_credentials file issue, which looks mysterious to me and would 
>> like to give this a dev try today.
>>
>> Thanks,
>>
>> Phil
>>
>>
>> On Wednesday, January 24, 2018 at 5:18:59 PM UTC-5, Jeremy Townson 
>> wrote:
>>>
>>> Hi Akka users,
>>>
>>> This is an update about Swakka, an addon for generating 
>>> OpenApi/Swagger docs with Akka-Http. I introduced Swakka in August last 
>>> year. Back then it was new, unstable and I recommended people not to 
>>> use 
>>> it. 
>>>
>>> Yesterday, I cut a v0.5 release. Whilst the library does not cover 
>>> Swagger 100%, it does cover everything in the Swagger’s famous 
>>> PetstoreV2 
>>> sample. Therefore it should document many real world APIs.
>>>
>>> If you are creating Akka-Http endpoints and have a need to document 
>>> them, I recommend you check out the project at 
>>> https://bitbucket.org/jtownson/swakka/. I hope it would help your 
>>> project and I would be really interested to hear your feedback.
>>>
>>> Beyond toughening up the library for a 1.0 release, I am also 
>>> starting to consider where to go next with the project. Thoughts in my 
>>> mind 
>>> right now are
>>> — do something completely different
>>> — support for other documentation formats like Api Blueprint or RAML.
>>> — having a close look at Akka-Http’s routing DSL, to see if there is 
>>> a refactor that would yield an AST. Now that Swakka can do doc 
>>> generation 
>>> from its OpenApi case class, if it _were_ possible to generate an AST 
>>> from 
>>> a Route structure, it might also be possible to map over that to 
>>> produce an 
>>> instance of OpenApi. Akka-Http users would then have the choice of 
>>> either 
>>> coding an OpenApi instance and getting Swakka to generate Routes, or 
>>> coding 
>>> Routes and generating OpenApi. I’m not convinced this is any more than 
>>> a 
>>> dream and I do not feel I have either the knowledge or authority to go 
>>> tinkering with one of the core abstractions in Akka-Http. But if this 
>>> interests you, you are familiar with the Akka-Http codebase and want to 
>>> take a punt as a pair, I’m game.
>>>
>>> All the best,
>>> Jeremy
>>>
>>> On Monday, 21 August 2017 10:54:44 UTC+1, Jeremy Townson wrote:

 Hi Akka Users,

 I would like to introduce *Swakka*, a library for adding 
 Swagger/OpenApi doc generation to akka-http. 
 https://bitbucket.org/jtownson/swakka.
  
 Like many people I was frustrated by the lack of swagger support in 
 akka-http. After reading the proposed solutions to the problem in 
 issue 
 201, "Support 

Re: [akka-user] Re: Swakka - a new extension to akka-http for Swagger/OpenApi

[Patrik Nordwall]

Thanks for the update Jeremey. Is the availability of this already
mentioned in akka-http documentation? Otherwise I think it would be worth
adding that somewhere. Please open an issue and we can work out the details.

regards,
Patrik
ons 31 jan. 2018 kl. 20:32 skrev Philippe Derome :

> never mind, it's not needed, I had communication with Spark in mind and
> that does not require to be in same process.
>
>
> On Wednesday, January 31, 2018 at 12:45:53 PM UTC-5, Philippe Derome wrote:
>>
>> Jeremy,
>>
>> do you have any intent to make this project available with Scala 2.11?
>>
>> Phil
>>
>>
>> On Tuesday, January 30, 2018 at 5:21:52 PM UTC-5, Jeremy Townson wrote:
>>>
>>> Thanks for reporting this, Philippe. For anybody who experienced this
>>> problem, fixed in
>>> https://bitbucket.org/jtownson/swakka/commits/0f5cb77196ea83135f9ca7913f1f111f6b39f369.
>>> Please pull from master.
>>>
>>> Actually I am planning a move to github soon, because of their really
>>> good usage stats.
>>>
>>> On Tuesday, 30 January 2018 19:56:26 UTC, Philippe Derome wrote:


 I had issues with credentials w.r. sonatype and removed all references
 thereof in build.sbt and plugins.sbt and this temporarily resolved my
 issues. I am not interested in publishing artifacts to an external site but
 perhaps you are.


 On Tuesday, January 30, 2018 at 10:08:06 AM UTC-5, Philippe Derome
 wrote:
>
> Would you consider migrating the project to github since you find it
> more stable now? I am unable to make use of it from bitbucket due to some
> sonatype_credentials file issue, which looks mysterious to me and would
> like to give this a dev try today.
>
> Thanks,
>
> Phil
>
>
> On Wednesday, January 24, 2018 at 5:18:59 PM UTC-5, Jeremy Townson
> wrote:
>>
>> Hi Akka users,
>>
>> This is an update about Swakka, an addon for generating
>> OpenApi/Swagger docs with Akka-Http. I introduced Swakka in August last
>> year. Back then it was new, unstable and I recommended people not to use
>> it.
>>
>> Yesterday, I cut a v0.5 release. Whilst the library does not cover
>> Swagger 100%, it does cover everything in the Swagger’s famous PetstoreV2
>> sample. Therefore it should document many real world APIs.
>>
>> If you are creating Akka-Http endpoints and have a need to document
>> them, I recommend you check out the project at
>> https://bitbucket.org/jtownson/swakka/. I hope it would help your
>> project and I would be really interested to hear your feedback.
>>
>> Beyond toughening up the library for a 1.0 release, I am also
>> starting to consider where to go next with the project. Thoughts in my 
>> mind
>> right now are
>> — do something completely different
>> — support for other documentation formats like Api Blueprint or RAML.
>> — having a close look at Akka-Http’s routing DSL, to see if there is
>> a refactor that would yield an AST. Now that Swakka can do doc generation
>> from its OpenApi case class, if it _were_ possible to generate an AST 
>> from
>> a Route structure, it might also be possible to map over that to produce 
>> an
>> instance of OpenApi. Akka-Http users would then have the choice of either
>> coding an OpenApi instance and getting Swakka to generate Routes, or 
>> coding
>> Routes and generating OpenApi. I’m not convinced this is any more than a
>> dream and I do not feel I have either the knowledge or authority to go
>> tinkering with one of the core abstractions in Akka-Http. But if this
>> interests you, you are familiar with the Akka-Http codebase and want to
>> take a punt as a pair, I’m game.
>>
>> All the best,
>> Jeremy
>>
>> On Monday, 21 August 2017 10:54:44 UTC+1, Jeremy Townson wrote:
>>>
>>> Hi Akka Users,
>>>
>>> I would like to introduce *Swakka*, a library for adding
>>> Swagger/OpenApi doc generation to akka-http.
>>> https://bitbucket.org/jtownson/swakka.
>>>
>>> Like many people I was frustrated by the lack of swagger support in
>>> akka-http. After reading the proposed solutions to the problem in issue
>>> 201, "Support Rest API doc generation" (
>>> https://github.com/akka/akka-http/issues/201) and trying
>>> swagger-akka-http (
>>> https://github.com/swagger-akka-http/swagger-akka-http), I decided
>>> to try a different approach.
>>>
>>> To briefly describe how Swakka works. One starts by instantiating an
>>> *OpenApi* case class that represent the structure of an API using
>>> Openapi/Swagger semantics. Swakka reads this API definition and 
>>> generates
>>> (a) an akka-http Route reflecting the swagger structure (extracting the
>>> parameters, paths, etc in your API definition) and (b) the swagger.json
>>> itself. The akka-http Route 

[akka-user] Re: Swakka - a new extension to akka-http for Swagger/OpenApi

[Philippe Derome]

never mind, it's not needed, I had communication with Spark in mind and 
that does not require to be in same process.

On Wednesday, January 31, 2018 at 12:45:53 PM UTC-5, Philippe Derome wrote:
>
> Jeremy,
>
> do you have any intent to make this project available with Scala 2.11? 
>
> Phil
>
>
> On Tuesday, January 30, 2018 at 5:21:52 PM UTC-5, Jeremy Townson wrote:
>>
>> Thanks for reporting this, Philippe. For anybody who experienced this 
>> problem, fixed in 
>> https://bitbucket.org/jtownson/swakka/commits/0f5cb77196ea83135f9ca7913f1f111f6b39f369.
>>  
>> Please pull from master.
>>
>> Actually I am planning a move to github soon, because of their really 
>> good usage stats.
>>
>> On Tuesday, 30 January 2018 19:56:26 UTC, Philippe Derome wrote:
>>>
>>>
>>> I had issues with credentials w.r. sonatype and removed all references 
>>> thereof in build.sbt and plugins.sbt and this temporarily resolved my 
>>> issues. I am not interested in publishing artifacts to an external site but 
>>> perhaps you are.
>>>
>>>
>>> On Tuesday, January 30, 2018 at 10:08:06 AM UTC-5, Philippe Derome wrote:

 Would you consider migrating the project to github since you find it 
 more stable now? I am unable to make use of it from bitbucket due to some 
 sonatype_credentials file issue, which looks mysterious to me and would 
 like to give this a dev try today.

 Thanks,

 Phil


 On Wednesday, January 24, 2018 at 5:18:59 PM UTC-5, Jeremy Townson 
 wrote:
>
> Hi Akka users,
>
> This is an update about Swakka, an addon for generating 
> OpenApi/Swagger docs with Akka-Http. I introduced Swakka in August last 
> year. Back then it was new, unstable and I recommended people not to use 
> it. 
>
> Yesterday, I cut a v0.5 release. Whilst the library does not cover 
> Swagger 100%, it does cover everything in the Swagger’s famous PetstoreV2 
> sample. Therefore it should document many real world APIs.
>
> If you are creating Akka-Http endpoints and have a need to document 
> them, I recommend you check out the project at 
> https://bitbucket.org/jtownson/swakka/. I hope it would help your 
> project and I would be really interested to hear your feedback.
>
> Beyond toughening up the library for a 1.0 release, I am also starting 
> to consider where to go next with the project. Thoughts in my mind right 
> now are
> — do something completely different
> — support for other documentation formats like Api Blueprint or RAML.
> — having a close look at Akka-Http’s routing DSL, to see if there is a 
> refactor that would yield an AST. Now that Swakka can do doc generation 
> from its OpenApi case class, if it _were_ possible to generate an AST 
> from 
> a Route structure, it might also be possible to map over that to produce 
> an 
> instance of OpenApi. Akka-Http users would then have the choice of either 
> coding an OpenApi instance and getting Swakka to generate Routes, or 
> coding 
> Routes and generating OpenApi. I’m not convinced this is any more than a 
> dream and I do not feel I have either the knowledge or authority to go 
> tinkering with one of the core abstractions in Akka-Http. But if this 
> interests you, you are familiar with the Akka-Http codebase and want to 
> take a punt as a pair, I’m game.
>
> All the best,
> Jeremy
>
> On Monday, 21 August 2017 10:54:44 UTC+1, Jeremy Townson wrote:
>>
>> Hi Akka Users,
>>
>> I would like to introduce *Swakka*, a library for adding 
>> Swagger/OpenApi doc generation to akka-http. 
>> https://bitbucket.org/jtownson/swakka.
>>  
>> Like many people I was frustrated by the lack of swagger support in 
>> akka-http. After reading the proposed solutions to the problem in issue 
>> 201, "Support Rest API doc generation" (
>> https://github.com/akka/akka-http/issues/201) and trying 
>> swagger-akka-http (
>> https://github.com/swagger-akka-http/swagger-akka-http), I decided 
>> to try a different approach.
>>
>> To briefly describe how Swakka works. One starts by instantiating an 
>> *OpenApi* case class that represent the structure of an API using 
>> Openapi/Swagger semantics. Swakka reads this API definition and 
>> generates 
>> (a) an akka-http Route reflecting the swagger structure (extracting the 
>> parameters, paths, etc in your API definition) and (b) the swagger.json 
>> itself. The akka-http Route in (a) serves the swagger.json file 
>> generated 
>> in (b) alongside your API.
>>
>> You provide nested, inner Routes as the implementations of the 
>> OpenApi endpoints. Thus you still have the full power of akka-http 
>> Directives that are not supported in Swagger.
>>
>> It's currently on bitbucket at https://bitbucket.org/jtownson/swakka. 

[akka-user] Re: Swakka - a new extension to akka-http for Swagger/OpenApi

[Philippe Derome]

Jeremy,

do you have any intent to make this project available with Scala 2.11? 

Phil


On Tuesday, January 30, 2018 at 5:21:52 PM UTC-5, Jeremy Townson wrote:
>
> Thanks for reporting this, Philippe. For anybody who experienced this 
> problem, fixed in 
> https://bitbucket.org/jtownson/swakka/commits/0f5cb77196ea83135f9ca7913f1f111f6b39f369.
>  
> Please pull from master.
>
> Actually I am planning a move to github soon, because of their really good 
> usage stats.
>
> On Tuesday, 30 January 2018 19:56:26 UTC, Philippe Derome wrote:
>>
>>
>> I had issues with credentials w.r. sonatype and removed all references 
>> thereof in build.sbt and plugins.sbt and this temporarily resolved my 
>> issues. I am not interested in publishing artifacts to an external site but 
>> perhaps you are.
>>
>>
>> On Tuesday, January 30, 2018 at 10:08:06 AM UTC-5, Philippe Derome wrote:
>>>
>>> Would you consider migrating the project to github since you find it 
>>> more stable now? I am unable to make use of it from bitbucket due to some 
>>> sonatype_credentials file issue, which looks mysterious to me and would 
>>> like to give this a dev try today.
>>>
>>> Thanks,
>>>
>>> Phil
>>>
>>>
>>> On Wednesday, January 24, 2018 at 5:18:59 PM UTC-5, Jeremy Townson wrote:

 Hi Akka users,

 This is an update about Swakka, an addon for generating OpenApi/Swagger 
 docs with Akka-Http. I introduced Swakka in August last year. Back then it 
 was new, unstable and I recommended people not to use it. 

 Yesterday, I cut a v0.5 release. Whilst the library does not cover 
 Swagger 100%, it does cover everything in the Swagger’s famous PetstoreV2 
 sample. Therefore it should document many real world APIs.

 If you are creating Akka-Http endpoints and have a need to document 
 them, I recommend you check out the project at 
 https://bitbucket.org/jtownson/swakka/. I hope it would help your 
 project and I would be really interested to hear your feedback.

 Beyond toughening up the library for a 1.0 release, I am also starting 
 to consider where to go next with the project. Thoughts in my mind right 
 now are
 — do something completely different
 — support for other documentation formats like Api Blueprint or RAML.
 — having a close look at Akka-Http’s routing DSL, to see if there is a 
 refactor that would yield an AST. Now that Swakka can do doc generation 
 from its OpenApi case class, if it _were_ possible to generate an AST from 
 a Route structure, it might also be possible to map over that to produce 
 an 
 instance of OpenApi. Akka-Http users would then have the choice of either 
 coding an OpenApi instance and getting Swakka to generate Routes, or 
 coding 
 Routes and generating OpenApi. I’m not convinced this is any more than a 
 dream and I do not feel I have either the knowledge or authority to go 
 tinkering with one of the core abstractions in Akka-Http. But if this 
 interests you, you are familiar with the Akka-Http codebase and want to 
 take a punt as a pair, I’m game.

 All the best,
 Jeremy

 On Monday, 21 August 2017 10:54:44 UTC+1, Jeremy Townson wrote:
>
> Hi Akka Users,
>
> I would like to introduce *Swakka*, a library for adding 
> Swagger/OpenApi doc generation to akka-http. 
> https://bitbucket.org/jtownson/swakka.
>  
> Like many people I was frustrated by the lack of swagger support in 
> akka-http. After reading the proposed solutions to the problem in issue 
> 201, "Support Rest API doc generation" (
> https://github.com/akka/akka-http/issues/201) and trying 
> swagger-akka-http (
> https://github.com/swagger-akka-http/swagger-akka-http), I decided to 
> try a different approach.
>
> To briefly describe how Swakka works. One starts by instantiating an 
> *OpenApi* case class that represent the structure of an API using 
> Openapi/Swagger semantics. Swakka reads this API definition and generates 
> (a) an akka-http Route reflecting the swagger structure (extracting the 
> parameters, paths, etc in your API definition) and (b) the swagger.json 
> itself. The akka-http Route in (a) serves the swagger.json file generated 
> in (b) alongside your API.
>
> You provide nested, inner Routes as the implementations of the OpenApi 
> endpoints. Thus you still have the full power of akka-http Directives 
> that 
> are not supported in Swagger.
>
> It's currently on bitbucket at https://bitbucket.org/jtownson/swakka. 
> I might move it to github at some point. It's in a early alpha state, not 
> finished, not stable and with quite a few bugs -- so not good for your 
> work 
> project yet. Nonetheless I am excited about the principle behind the 
> library, so I wanted to put it out there.
>
> If you are willing and able to 

[akka-user] Re: Swakka - a new extension to akka-http for Swagger/OpenApi

[Jeremy Townson]

Thanks for reporting this, Philippe. For anybody who experienced this 
problem, fixed in 
https://bitbucket.org/jtownson/swakka/commits/0f5cb77196ea83135f9ca7913f1f111f6b39f369.
 
Please pull from master.

Actually I am planning a move to github soon, because of their really good 
usage stats.

On Tuesday, 30 January 2018 19:56:26 UTC, Philippe Derome wrote:
>
>
> I had issues with credentials w.r. sonatype and removed all references 
> thereof in build.sbt and plugins.sbt and this temporarily resolved my 
> issues. I am not interested in publishing artifacts to an external site but 
> perhaps you are.
>
>
> On Tuesday, January 30, 2018 at 10:08:06 AM UTC-5, Philippe Derome wrote:
>>
>> Would you consider migrating the project to github since you find it more 
>> stable now? I am unable to make use of it from bitbucket due to some 
>> sonatype_credentials file issue, which looks mysterious to me and would 
>> like to give this a dev try today.
>>
>> Thanks,
>>
>> Phil
>>
>>
>> On Wednesday, January 24, 2018 at 5:18:59 PM UTC-5, Jeremy Townson wrote:
>>>
>>> Hi Akka users,
>>>
>>> This is an update about Swakka, an addon for generating OpenApi/Swagger 
>>> docs with Akka-Http. I introduced Swakka in August last year. Back then it 
>>> was new, unstable and I recommended people not to use it. 
>>>
>>> Yesterday, I cut a v0.5 release. Whilst the library does not cover 
>>> Swagger 100%, it does cover everything in the Swagger’s famous PetstoreV2 
>>> sample. Therefore it should document many real world APIs.
>>>
>>> If you are creating Akka-Http endpoints and have a need to document 
>>> them, I recommend you check out the project at 
>>> https://bitbucket.org/jtownson/swakka/. I hope it would help your 
>>> project and I would be really interested to hear your feedback.
>>>
>>> Beyond toughening up the library for a 1.0 release, I am also starting 
>>> to consider where to go next with the project. Thoughts in my mind right 
>>> now are
>>> — do something completely different
>>> — support for other documentation formats like Api Blueprint or RAML.
>>> — having a close look at Akka-Http’s routing DSL, to see if there is a 
>>> refactor that would yield an AST. Now that Swakka can do doc generation 
>>> from its OpenApi case class, if it _were_ possible to generate an AST from 
>>> a Route structure, it might also be possible to map over that to produce an 
>>> instance of OpenApi. Akka-Http users would then have the choice of either 
>>> coding an OpenApi instance and getting Swakka to generate Routes, or coding 
>>> Routes and generating OpenApi. I’m not convinced this is any more than a 
>>> dream and I do not feel I have either the knowledge or authority to go 
>>> tinkering with one of the core abstractions in Akka-Http. But if this 
>>> interests you, you are familiar with the Akka-Http codebase and want to 
>>> take a punt as a pair, I’m game.
>>>
>>> All the best,
>>> Jeremy
>>>
>>> On Monday, 21 August 2017 10:54:44 UTC+1, Jeremy Townson wrote:

 Hi Akka Users,

 I would like to introduce *Swakka*, a library for adding 
 Swagger/OpenApi doc generation to akka-http. 
 https://bitbucket.org/jtownson/swakka.
  
 Like many people I was frustrated by the lack of swagger support in 
 akka-http. After reading the proposed solutions to the problem in issue 
 201, "Support Rest API doc generation" (
 https://github.com/akka/akka-http/issues/201) and trying 
 swagger-akka-http (
 https://github.com/swagger-akka-http/swagger-akka-http), I decided to 
 try a different approach.

 To briefly describe how Swakka works. One starts by instantiating an 
 *OpenApi* case class that represent the structure of an API using 
 Openapi/Swagger semantics. Swakka reads this API definition and generates 
 (a) an akka-http Route reflecting the swagger structure (extracting the 
 parameters, paths, etc in your API definition) and (b) the swagger.json 
 itself. The akka-http Route in (a) serves the swagger.json file generated 
 in (b) alongside your API.

 You provide nested, inner Routes as the implementations of the OpenApi 
 endpoints. Thus you still have the full power of akka-http Directives that 
 are not supported in Swagger.

 It's currently on bitbucket at https://bitbucket.org/jtownson/swakka. 
 I might move it to github at some point. It's in a early alpha state, not 
 finished, not stable and with quite a few bugs -- so not good for your 
 work 
 project yet. Nonetheless I am excited about the principle behind the 
 library, so I wanted to put it out there.

 If you are willing and able to contribute to Swakka then I would be 
 interested to hear from you. The roadmap in my mind for the next 3-6 
 months 
 is
 -- ease of use improvements
 -- full OpenApi 2 support
 -- bugfixes and documentation consistent with 1.0 release.

 Read more about it at 

[akka-user] Re: Swakka - a new extension to akka-http for Swagger/OpenApi

[Philippe Derome]

I had issues with credentials w.r. sonatype and removed all references 
thereof in build.sbt and plugins.sbt and this temporarily resolved my 
issues. I am not interested in publishing artifacts to an external site but 
perhaps you are.


On Tuesday, January 30, 2018 at 10:08:06 AM UTC-5, Philippe Derome wrote:
>
> Would you consider migrating the project to github since you find it more 
> stable now? I am unable to make use of it from bitbucket due to some 
> sonatype_credentials file issue, which looks mysterious to me and would 
> like to give this a dev try today.
>
> Thanks,
>
> Phil
>
>
> On Wednesday, January 24, 2018 at 5:18:59 PM UTC-5, Jeremy Townson wrote:
>>
>> Hi Akka users,
>>
>> This is an update about Swakka, an addon for generating OpenApi/Swagger 
>> docs with Akka-Http. I introduced Swakka in August last year. Back then it 
>> was new, unstable and I recommended people not to use it. 
>>
>> Yesterday, I cut a v0.5 release. Whilst the library does not cover 
>> Swagger 100%, it does cover everything in the Swagger’s famous PetstoreV2 
>> sample. Therefore it should document many real world APIs.
>>
>> If you are creating Akka-Http endpoints and have a need to document them, 
>> I recommend you check out the project at 
>> https://bitbucket.org/jtownson/swakka/. I hope it would help your 
>> project and I would be really interested to hear your feedback.
>>
>> Beyond toughening up the library for a 1.0 release, I am also starting to 
>> consider where to go next with the project. Thoughts in my mind right now 
>> are
>> — do something completely different
>> — support for other documentation formats like Api Blueprint or RAML.
>> — having a close look at Akka-Http’s routing DSL, to see if there is a 
>> refactor that would yield an AST. Now that Swakka can do doc generation 
>> from its OpenApi case class, if it _were_ possible to generate an AST from 
>> a Route structure, it might also be possible to map over that to produce an 
>> instance of OpenApi. Akka-Http users would then have the choice of either 
>> coding an OpenApi instance and getting Swakka to generate Routes, or coding 
>> Routes and generating OpenApi. I’m not convinced this is any more than a 
>> dream and I do not feel I have either the knowledge or authority to go 
>> tinkering with one of the core abstractions in Akka-Http. But if this 
>> interests you, you are familiar with the Akka-Http codebase and want to 
>> take a punt as a pair, I’m game.
>>
>> All the best,
>> Jeremy
>>
>> On Monday, 21 August 2017 10:54:44 UTC+1, Jeremy Townson wrote:
>>>
>>> Hi Akka Users,
>>>
>>> I would like to introduce *Swakka*, a library for adding 
>>> Swagger/OpenApi doc generation to akka-http. 
>>> https://bitbucket.org/jtownson/swakka.
>>>  
>>> Like many people I was frustrated by the lack of swagger support in 
>>> akka-http. After reading the proposed solutions to the problem in issue 
>>> 201, "Support Rest API doc generation" (
>>> https://github.com/akka/akka-http/issues/201) and trying 
>>> swagger-akka-http (
>>> https://github.com/swagger-akka-http/swagger-akka-http), I decided to 
>>> try a different approach.
>>>
>>> To briefly describe how Swakka works. One starts by instantiating an 
>>> *OpenApi* case class that represent the structure of an API using 
>>> Openapi/Swagger semantics. Swakka reads this API definition and generates 
>>> (a) an akka-http Route reflecting the swagger structure (extracting the 
>>> parameters, paths, etc in your API definition) and (b) the swagger.json 
>>> itself. The akka-http Route in (a) serves the swagger.json file generated 
>>> in (b) alongside your API.
>>>
>>> You provide nested, inner Routes as the implementations of the OpenApi 
>>> endpoints. Thus you still have the full power of akka-http Directives that 
>>> are not supported in Swagger.
>>>
>>> It's currently on bitbucket at https://bitbucket.org/jtownson/swakka. I 
>>> might move it to github at some point. It's in a early alpha state, not 
>>> finished, not stable and with quite a few bugs -- so not good for your work 
>>> project yet. Nonetheless I am excited about the principle behind the 
>>> library, so I wanted to put it out there.
>>>
>>> If you are willing and able to contribute to Swakka then I would be 
>>> interested to hear from you. The roadmap in my mind for the next 3-6 months 
>>> is
>>> -- ease of use improvements
>>> -- full OpenApi 2 support
>>> -- bugfixes and documentation consistent with 1.0 release.
>>>
>>> Read more about it at https://bitbucket.org/jtownson/swakka.
>>>
>>> Have fun,
>>> Jeremy
>>>
>>>

-- 
>>  Read the docs: http://akka.io/docs/
>>  Check the FAQ: 
>> http://doc.akka.io/docs/akka/current/additional/faq.html
>>  Search the archives: https://groups.google.com/group/akka-user
--- 
You received this message because you are subscribed to the Google Groups "Akka 
User List" group.
To unsubscribe from this group and stop receiving emails from 

[akka-user] Re: Swakka - a new extension to akka-http for Swagger/OpenApi

[Philippe Derome]

Would you consider migrating the project to github since you find it more 
stable now? I am unable to make use of it from bitbucket due to some 
sonatype_credentials file issue, which looks mysterious to me and would 
like to give this a dev try today.

Thanks,

Phil


On Wednesday, January 24, 2018 at 5:18:59 PM UTC-5, Jeremy Townson wrote:
>
> Hi Akka users,
>
> This is an update about Swakka, an addon for generating OpenApi/Swagger 
> docs with Akka-Http. I introduced Swakka in August last year. Back then it 
> was new, unstable and I recommended people not to use it. 
>
> Yesterday, I cut a v0.5 release. Whilst the library does not cover Swagger 
> 100%, it does cover everything in the Swagger’s famous PetstoreV2 sample. 
> Therefore it should document many real world APIs.
>
> If you are creating Akka-Http endpoints and have a need to document them, 
> I recommend you check out the project at 
> https://bitbucket.org/jtownson/swakka/. I hope it would help your project 
> and I would be really interested to hear your feedback.
>
> Beyond toughening up the library for a 1.0 release, I am also starting to 
> consider where to go next with the project. Thoughts in my mind right now 
> are
> — do something completely different
> — support for other documentation formats like Api Blueprint or RAML.
> — having a close look at Akka-Http’s routing DSL, to see if there is a 
> refactor that would yield an AST. Now that Swakka can do doc generation 
> from its OpenApi case class, if it _were_ possible to generate an AST from 
> a Route structure, it might also be possible to map over that to produce an 
> instance of OpenApi. Akka-Http users would then have the choice of either 
> coding an OpenApi instance and getting Swakka to generate Routes, or coding 
> Routes and generating OpenApi. I’m not convinced this is any more than a 
> dream and I do not feel I have either the knowledge or authority to go 
> tinkering with one of the core abstractions in Akka-Http. But if this 
> interests you, you are familiar with the Akka-Http codebase and want to 
> take a punt as a pair, I’m game.
>
> All the best,
> Jeremy
>
> On Monday, 21 August 2017 10:54:44 UTC+1, Jeremy Townson wrote:
>>
>> Hi Akka Users,
>>
>> I would like to introduce *Swakka*, a library for adding Swagger/OpenApi 
>> doc generation to akka-http. https://bitbucket.org/jtownson/swakka.
>>  
>> Like many people I was frustrated by the lack of swagger support in 
>> akka-http. After reading the proposed solutions to the problem in issue 
>> 201, "Support Rest API doc generation" (
>> https://github.com/akka/akka-http/issues/201) and trying 
>> swagger-akka-http (https://github.com/swagger-akka-http/swagger-akka-http), 
>> I decided to try a different approach.
>>
>> To briefly describe how Swakka works. One starts by instantiating an 
>> *OpenApi* case class that represent the structure of an API using 
>> Openapi/Swagger semantics. Swakka reads this API definition and generates 
>> (a) an akka-http Route reflecting the swagger structure (extracting the 
>> parameters, paths, etc in your API definition) and (b) the swagger.json 
>> itself. The akka-http Route in (a) serves the swagger.json file generated 
>> in (b) alongside your API.
>>
>> You provide nested, inner Routes as the implementations of the OpenApi 
>> endpoints. Thus you still have the full power of akka-http Directives that 
>> are not supported in Swagger.
>>
>> It's currently on bitbucket at https://bitbucket.org/jtownson/swakka. I 
>> might move it to github at some point. It's in a early alpha state, not 
>> finished, not stable and with quite a few bugs -- so not good for your work 
>> project yet. Nonetheless I am excited about the principle behind the 
>> library, so I wanted to put it out there.
>>
>> If you are willing and able to contribute to Swakka then I would be 
>> interested to hear from you. The roadmap in my mind for the next 3-6 months 
>> is
>> -- ease of use improvements
>> -- full OpenApi 2 support
>> -- bugfixes and documentation consistent with 1.0 release.
>>
>> Read more about it at https://bitbucket.org/jtownson/swakka.
>>
>> Have fun,
>> Jeremy
>>
>>

-- 
>>  Read the docs: http://akka.io/docs/
>>  Check the FAQ: 
>> http://doc.akka.io/docs/akka/current/additional/faq.html
>>  Search the archives: https://groups.google.com/group/akka-user
--- 
You received this message because you are subscribed to the Google Groups "Akka 
User List" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to akka-user+unsubscr...@googlegroups.com.
To post to this group, send email to akka-user@googlegroups.com.
Visit this group at https://groups.google.com/group/akka-user.
For more options, visit https://groups.google.com/d/optout.

[akka-user] Re: Swakka - a new extension to akka-http for Swagger/OpenApi

[Philippe Derome]

thanks!

On Sunday, January 28, 2018 at 4:34:37 AM UTC-5, Jeremy Townson wrote:
>
> Hi Phil,
>
> Sorry, I do not have much experience with REST books beyond having glanced 
> through "Rest in practice" and "the restful web services cookbook". These 
> are good resources. I have always tried to remain conscious of how your API 
> will appear to the user. It is easy to start with that mindset but lose it 
> over time. Of special importance is how easy your API is to pick up and use 
> for the first time.
>
> Good luck.
>
> Regards,
> Jeremy
>
> On Sunday, 28 January 2018 03:31:37 UTC, Philippe Derome wrote:
>>
>> It helps a great deal actually. Prior to reading your response this 
>> evening, I came to realize that indeed your solution is unique in type 
>> safety and avoiding annotations. I switched from C++ to Java 2-3 years ago 
>> and so never got into the world of Spring framework and annotations and 
>> didn't like the few annotations when dealing with Play or Guice. I haven't 
>> worked with Akka-Http yet but did work with Akka core and that went well 
>> enough. In short, I see annotations as stop gap measures and don't want to 
>> rely upon them. I also heard from the community (scala/fr in this instance) 
>> a strong reluctance to work with code generation, and your project avoids 
>> that as well. I read diagonally the description of your project and it does 
>> look very promising (support for Options and HLists, not just Products, and 
>> support for OAuth security).
>>
>> I also noticed some code generation project with Lagom/Swagger that does 
>> not build on CI, which was worrisome.
>>
>> If you have any insight on great book about web api design (principally 
>> REST based but not necessarily exclusively so), do you have 
>> recommendations? I see Irresistible APIs by Kirsten L. Hunter (at Manning) 
>> and two-three books by Matthias Biehl (API University Series) among recent 
>> contributions.
>>
>> Thanks much!
>>
>> Phil
>>
>>
>> On Saturday, January 27, 2018 at 7:19:35 PM UTC-5, Jeremy Townson wrote:
>>>
>>> Hi Phil,
>>>
>>> I would point out that:
>>> -- To support HTTP, Lagom uses *Play*. Currently, to create swagger docs 
>>> for APIs written with Play, you typically use Swagger *annotations*, as 
>>> supported by 
>>> https://github.com/swagger-api/swagger-play/tree/master/play-2.6/swagger-play2
>>> .
>>> -- Although the Lagom code generator is the start of another route to 
>>> Swagger docs, it looks very immature and poorly maintained. See 
>>> https://github.com/lagom/lagom/issues/280. (Apologies to Lagom if the 
>>> code is now maintained elsewhere).
>>> -- Lagom code generator is a *code generator*. That's to say, it is part 
>>> of your build pipeline.
>>>
>>> By contrast:
>>> -- Swakka works with Akka-Http (not play). And, as everybody on this 
>>> list will testify, Akka-Http is *much* better than Play:-)
>>> -- Swakka does not use the Swagger annotations. Instead, the API 
>>> metadata goes into *case classes*.
>>> -- Swakka is not a build-time code generator. It uses scala functions at 
>>> runtime, which are run when the akka-http server boots up.
>>>
>>> In my opinion (but only my opinion):
>>> -- Lagom probably makes a lot of sense for an architect in a large 
>>> organization with a lightbend support contract, trying to achieve 
>>> consistency of tech across a number of teams. But as a developer, I would 
>>> not use it. It makes more sense to pick and chose the tools you need on a 
>>> case by case basis (not to imply that Lagom's stack is poor in any way, but 
>>> why tie one's self to it?).
>>> -- a key decision for new web projects is often where to use Akka-Http 
>>> or Play. I hope that, from an API doc perspective, Swakka now makes 
>>> Akka-Http the better choice, but the overall decision is obviously wider 
>>> than just API docs.
>>>
>>> Hope that is of some help.
>>>
>>> On Saturday, 27 January 2018 17:25:06 UTC, Philippe Derome wrote:

 Jeremy,

 do you have familiarity with the Lagom Code Generator project 
  
 ? 
 I am interested in building web services using Lightbend technologies 
 (Akka-Http and/or Lagom) while leveraging Swagger documentation of APIs 
 for 
 external clients/consumers. If you have familiarity with stated Lagom 
 project, I'd appreciate your views on the two approaches, i.e. that and 
 Swakka.

 Thanks,

 Phil

 On Wednesday, January 24, 2018 at 5:18:59 PM UTC-5, Jeremy Townson 
 wrote:
>
> Hi Akka users,
>
> This is an update about Swakka, an addon for generating 
> OpenApi/Swagger docs with Akka-Http. I introduced Swakka in August last 
> year. Back then it was new, unstable and I recommended people not to use 
> it. 
>
> Yesterday, I cut a v0.5 release. Whilst the library does not cover 
> Swagger 100%, it does cover everything in the Swagger’s 

[akka-user] Re: Swakka - a new extension to akka-http for Swagger/OpenApi

[Jeremy Townson]

Hi Phil,

Sorry, I do not have much experience with REST books beyond having glanced 
through "Rest in practice" and "the restful web services cookbook". These 
are good resources. I have always tried to remain conscious of how your API 
will appear to the user. It is easy to start with that mindset but lose it 
over time. Of special importance is how easy your API is to pick up and use 
for the first time.

Good luck.

Regards,
Jeremy

On Sunday, 28 January 2018 03:31:37 UTC, Philippe Derome wrote:
>
> It helps a great deal actually. Prior to reading your response this 
> evening, I came to realize that indeed your solution is unique in type 
> safety and avoiding annotations. I switched from C++ to Java 2-3 years ago 
> and so never got into the world of Spring framework and annotations and 
> didn't like the few annotations when dealing with Play or Guice. I haven't 
> worked with Akka-Http yet but did work with Akka core and that went well 
> enough. In short, I see annotations as stop gap measures and don't want to 
> rely upon them. I also heard from the community (scala/fr in this instance) 
> a strong reluctance to work with code generation, and your project avoids 
> that as well. I read diagonally the description of your project and it does 
> look very promising (support for Options and HLists, not just Products, and 
> support for OAuth security).
>
> I also noticed some code generation project with Lagom/Swagger that does 
> not build on CI, which was worrisome.
>
> If you have any insight on great book about web api design (principally 
> REST based but not necessarily exclusively so), do you have 
> recommendations? I see Irresistible APIs by Kirsten L. Hunter (at Manning) 
> and two-three books by Matthias Biehl (API University Series) among recent 
> contributions.
>
> Thanks much!
>
> Phil
>
>
> On Saturday, January 27, 2018 at 7:19:35 PM UTC-5, Jeremy Townson wrote:
>>
>> Hi Phil,
>>
>> I would point out that:
>> -- To support HTTP, Lagom uses *Play*. Currently, to create swagger docs 
>> for APIs written with Play, you typically use Swagger *annotations*, as 
>> supported by 
>> https://github.com/swagger-api/swagger-play/tree/master/play-2.6/swagger-play2
>> .
>> -- Although the Lagom code generator is the start of another route to 
>> Swagger docs, it looks very immature and poorly maintained. See 
>> https://github.com/lagom/lagom/issues/280. (Apologies to Lagom if the 
>> code is now maintained elsewhere).
>> -- Lagom code generator is a *code generator*. That's to say, it is part 
>> of your build pipeline.
>>
>> By contrast:
>> -- Swakka works with Akka-Http (not play). And, as everybody on this list 
>> will testify, Akka-Http is *much* better than Play:-)
>> -- Swakka does not use the Swagger annotations. Instead, the API metadata 
>> goes into *case classes*.
>> -- Swakka is not a build-time code generator. It uses scala functions at 
>> runtime, which are run when the akka-http server boots up.
>>
>> In my opinion (but only my opinion):
>> -- Lagom probably makes a lot of sense for an architect in a large 
>> organization with a lightbend support contract, trying to achieve 
>> consistency of tech across a number of teams. But as a developer, I would 
>> not use it. It makes more sense to pick and chose the tools you need on a 
>> case by case basis (not to imply that Lagom's stack is poor in any way, but 
>> why tie one's self to it?).
>> -- a key decision for new web projects is often where to use Akka-Http or 
>> Play. I hope that, from an API doc perspective, Swakka now makes Akka-Http 
>> the better choice, but the overall decision is obviously wider than just 
>> API docs.
>>
>> Hope that is of some help.
>>
>> On Saturday, 27 January 2018 17:25:06 UTC, Philippe Derome wrote:
>>>
>>> Jeremy,
>>>
>>> do you have familiarity with the Lagom Code Generator project 
>>>  
>>> ? 
>>> I am interested in building web services using Lightbend technologies 
>>> (Akka-Http and/or Lagom) while leveraging Swagger documentation of APIs for 
>>> external clients/consumers. If you have familiarity with stated Lagom 
>>> project, I'd appreciate your views on the two approaches, i.e. that and 
>>> Swakka.
>>>
>>> Thanks,
>>>
>>> Phil
>>>
>>> On Wednesday, January 24, 2018 at 5:18:59 PM UTC-5, Jeremy Townson wrote:

 Hi Akka users,

 This is an update about Swakka, an addon for generating OpenApi/Swagger 
 docs with Akka-Http. I introduced Swakka in August last year. Back then it 
 was new, unstable and I recommended people not to use it. 

 Yesterday, I cut a v0.5 release. Whilst the library does not cover 
 Swagger 100%, it does cover everything in the Swagger’s famous PetstoreV2 
 sample. Therefore it should document many real world APIs.

 If you are creating Akka-Http endpoints and have a need to document 
 them, I recommend you check out the project at 
 

[akka-user] Re: Swakka - a new extension to akka-http for Swagger/OpenApi

[Philippe Derome]

It helps a great deal actually. Prior to reading your response this 
evening, I came to realize that indeed your solution is unique in type 
safety and avoiding annotations. I switched from C++ to Java 2-3 years ago 
and so never got into the world of Spring framework and annotations and 
didn't like the few annotations when dealing with Play or Guice. I haven't 
worked with Akka-Http yet but did work with Akka core and that went well 
enough. In short, I see annotations as stop gap measures and don't want to 
rely upon them. I also heard from the community (scala/fr in this instance) 
a strong reluctance to work with code generation, and your project avoids 
that as well. I read diagonally the description of your project and it does 
look very promising (support for Options and HLists, not just Products, and 
support for OAuth security).

I also noticed some code generation project with Lagom/Swagger that does 
not build on CI, which was worrisome.

If you have any insight on great book about web api design (principally 
REST based but not necessarily exclusively so), do you have 
recommendations? I see Irresistible APIs by Kirsten L. Hunter (at Manning) 
and two-three books by Matthias Biehl (API University Series) among recent 
contributions.

Thanks much!

Phil


On Saturday, January 27, 2018 at 7:19:35 PM UTC-5, Jeremy Townson wrote:
>
> Hi Phil,
>
> I would point out that:
> -- To support HTTP, Lagom uses *Play*. Currently, to create swagger docs 
> for APIs written with Play, you typically use Swagger *annotations*, as 
> supported by 
> https://github.com/swagger-api/swagger-play/tree/master/play-2.6/swagger-play2
> .
> -- Although the Lagom code generator is the start of another route to 
> Swagger docs, it looks very immature and poorly maintained. See 
> https://github.com/lagom/lagom/issues/280. (Apologies to Lagom if the 
> code is now maintained elsewhere).
> -- Lagom code generator is a *code generator*. That's to say, it is part 
> of your build pipeline.
>
> By contrast:
> -- Swakka works with Akka-Http (not play). And, as everybody on this list 
> will testify, Akka-Http is *much* better than Play:-)
> -- Swakka does not use the Swagger annotations. Instead, the API metadata 
> goes into *case classes*.
> -- Swakka is not a build-time code generator. It uses scala functions at 
> runtime, which are run when the akka-http server boots up.
>
> In my opinion (but only my opinion):
> -- Lagom probably makes a lot of sense for an architect in a large 
> organization with a lightbend support contract, trying to achieve 
> consistency of tech across a number of teams. But as a developer, I would 
> not use it. It makes more sense to pick and chose the tools you need on a 
> case by case basis (not to imply that Lagom's stack is poor in any way, but 
> why tie one's self to it?).
> -- a key decision for new web projects is often where to use Akka-Http or 
> Play. I hope that, from an API doc perspective, Swakka now makes Akka-Http 
> the better choice, but the overall decision is obviously wider than just 
> API docs.
>
> Hope that is of some help.
>
> On Saturday, 27 January 2018 17:25:06 UTC, Philippe Derome wrote:
>>
>> Jeremy,
>>
>> do you have familiarity with the Lagom Code Generator project 
>>  ? 
>> I am interested in building web services using Lightbend technologies 
>> (Akka-Http and/or Lagom) while leveraging Swagger documentation of APIs for 
>> external clients/consumers. If you have familiarity with stated Lagom 
>> project, I'd appreciate your views on the two approaches, i.e. that and 
>> Swakka.
>>
>> Thanks,
>>
>> Phil
>>
>> On Wednesday, January 24, 2018 at 5:18:59 PM UTC-5, Jeremy Townson wrote:
>>>
>>> Hi Akka users,
>>>
>>> This is an update about Swakka, an addon for generating OpenApi/Swagger 
>>> docs with Akka-Http. I introduced Swakka in August last year. Back then it 
>>> was new, unstable and I recommended people not to use it. 
>>>
>>> Yesterday, I cut a v0.5 release. Whilst the library does not cover 
>>> Swagger 100%, it does cover everything in the Swagger’s famous PetstoreV2 
>>> sample. Therefore it should document many real world APIs.
>>>
>>> If you are creating Akka-Http endpoints and have a need to document 
>>> them, I recommend you check out the project at 
>>> https://bitbucket.org/jtownson/swakka/. I hope it would help your 
>>> project and I would be really interested to hear your feedback.
>>>
>>> Beyond toughening up the library for a 1.0 release, I am also starting 
>>> to consider where to go next with the project. Thoughts in my mind right 
>>> now are
>>> — do something completely different
>>> — support for other documentation formats like Api Blueprint or RAML.
>>> — having a close look at Akka-Http’s routing DSL, to see if there is a 
>>> refactor that would yield an AST. Now that Swakka can do doc generation 
>>> from its OpenApi case class, if it _were_ possible to 

[akka-user] Re: Swakka - a new extension to akka-http for Swagger/OpenApi

[Jeremy Townson]

Hi Phil,

I would point out that:
-- To support HTTP, Lagom uses *Play*. Currently, to create swagger docs 
for APIs written with Play, you typically use Swagger *annotations*, as 
supported by 
https://github.com/swagger-api/swagger-play/tree/master/play-2.6/swagger-play2.
-- Although the Lagom code generator is the start of another route to 
Swagger docs, it looks very immature and poorly maintained. See 
https://github.com/lagom/lagom/issues/280. (Apologies to Lagom if the code 
is now maintained elsewhere).
-- Lagom code generator is a *code generator*. That's to say, it is part of 
your build pipeline.

By contrast:
-- Swakka works with Akka-Http (not play). And, as everybody on this list 
will testify, Akka-Http is *much* better than Play:-)
-- Swakka does not use the Swagger annotations. Instead, the API metadata 
goes into *case classes*.
-- Swakka is not a build-time code generator. It uses scala functions at 
runtime, which are run when the akka-http server boots up.

In my opinion (but only my opinion):
-- Lagom probably makes a lot of sense for an architect in a large 
organization with a lightbend support contract, trying to achieve 
consistency of tech across a number of teams. But as a developer, I would 
not use it. It makes more sense to pick and chose the tools you need on a 
case by case basis (not to imply that Lagom's stack is poor in any way, but 
why tie one's self to it?).
-- a key decision for new web projects is often where to use Akka-Http or 
Play. I hope that, from an API doc perspective, Swakka now makes Akka-Http 
the better choice, but the overall decision is obviously wider than just 
API docs.

Hope that is of some help.

On Saturday, 27 January 2018 17:25:06 UTC, Philippe Derome wrote:
>
> Jeremy,
>
> do you have familiarity with the Lagom Code Generator project 
>  ? 
> I am interested in building web services using Lightbend technologies 
> (Akka-Http and/or Lagom) while leveraging Swagger documentation of APIs for 
> external clients/consumers. If you have familiarity with stated Lagom 
> project, I'd appreciate your views on the two approaches, i.e. that and 
> Swakka.
>
> Thanks,
>
> Phil
>
> On Wednesday, January 24, 2018 at 5:18:59 PM UTC-5, Jeremy Townson wrote:
>>
>> Hi Akka users,
>>
>> This is an update about Swakka, an addon for generating OpenApi/Swagger 
>> docs with Akka-Http. I introduced Swakka in August last year. Back then it 
>> was new, unstable and I recommended people not to use it. 
>>
>> Yesterday, I cut a v0.5 release. Whilst the library does not cover 
>> Swagger 100%, it does cover everything in the Swagger’s famous PetstoreV2 
>> sample. Therefore it should document many real world APIs.
>>
>> If you are creating Akka-Http endpoints and have a need to document them, 
>> I recommend you check out the project at 
>> https://bitbucket.org/jtownson/swakka/. I hope it would help your 
>> project and I would be really interested to hear your feedback.
>>
>> Beyond toughening up the library for a 1.0 release, I am also starting to 
>> consider where to go next with the project. Thoughts in my mind right now 
>> are
>> — do something completely different
>> — support for other documentation formats like Api Blueprint or RAML.
>> — having a close look at Akka-Http’s routing DSL, to see if there is a 
>> refactor that would yield an AST. Now that Swakka can do doc generation 
>> from its OpenApi case class, if it _were_ possible to generate an AST from 
>> a Route structure, it might also be possible to map over that to produce an 
>> instance of OpenApi. Akka-Http users would then have the choice of either 
>> coding an OpenApi instance and getting Swakka to generate Routes, or coding 
>> Routes and generating OpenApi. I’m not convinced this is any more than a 
>> dream and I do not feel I have either the knowledge or authority to go 
>> tinkering with one of the core abstractions in Akka-Http. But if this 
>> interests you, you are familiar with the Akka-Http codebase and want to 
>> take a punt as a pair, I’m game.
>>
>> All the best,
>> Jeremy
>>
>> On Monday, 21 August 2017 10:54:44 UTC+1, Jeremy Townson wrote:
>>>
>>> Hi Akka Users,
>>>
>>> I would like to introduce *Swakka*, a library for adding 
>>> Swagger/OpenApi doc generation to akka-http. 
>>> https://bitbucket.org/jtownson/swakka.
>>>  
>>> Like many people I was frustrated by the lack of swagger support in 
>>> akka-http. After reading the proposed solutions to the problem in issue 
>>> 201, "Support Rest API doc generation" (
>>> https://github.com/akka/akka-http/issues/201) and trying 
>>> swagger-akka-http (
>>> https://github.com/swagger-akka-http/swagger-akka-http), I decided to 
>>> try a different approach.
>>>
>>> To briefly describe how Swakka works. One starts by instantiating an 
>>> *OpenApi* case class that represent the structure of an API using 
>>> Openapi/Swagger semantics. Swakka reads this API 

[akka-user] Re: Swakka - a new extension to akka-http for Swagger/OpenApi

[Philippe Derome]

Jeremy,

do you have familiarity with the Lagom Code Generator project 
 ? 
I am interested in building web services using Lightbend technologies 
(Akka-Http and/or Lagom) while leveraging Swagger documentation of APIs for 
external clients/consumers. If you have familiarity with stated Lagom 
project, I'd appreciate your views on the two approaches, i.e. that and 
Swakka.

Thanks,

Phil

On Wednesday, January 24, 2018 at 5:18:59 PM UTC-5, Jeremy Townson wrote:
>
> Hi Akka users,
>
> This is an update about Swakka, an addon for generating OpenApi/Swagger 
> docs with Akka-Http. I introduced Swakka in August last year. Back then it 
> was new, unstable and I recommended people not to use it. 
>
> Yesterday, I cut a v0.5 release. Whilst the library does not cover Swagger 
> 100%, it does cover everything in the Swagger’s famous PetstoreV2 sample. 
> Therefore it should document many real world APIs.
>
> If you are creating Akka-Http endpoints and have a need to document them, 
> I recommend you check out the project at 
> https://bitbucket.org/jtownson/swakka/. I hope it would help your project 
> and I would be really interested to hear your feedback.
>
> Beyond toughening up the library for a 1.0 release, I am also starting to 
> consider where to go next with the project. Thoughts in my mind right now 
> are
> — do something completely different
> — support for other documentation formats like Api Blueprint or RAML.
> — having a close look at Akka-Http’s routing DSL, to see if there is a 
> refactor that would yield an AST. Now that Swakka can do doc generation 
> from its OpenApi case class, if it _were_ possible to generate an AST from 
> a Route structure, it might also be possible to map over that to produce an 
> instance of OpenApi. Akka-Http users would then have the choice of either 
> coding an OpenApi instance and getting Swakka to generate Routes, or coding 
> Routes and generating OpenApi. I’m not convinced this is any more than a 
> dream and I do not feel I have either the knowledge or authority to go 
> tinkering with one of the core abstractions in Akka-Http. But if this 
> interests you, you are familiar with the Akka-Http codebase and want to 
> take a punt as a pair, I’m game.
>
> All the best,
> Jeremy
>
> On Monday, 21 August 2017 10:54:44 UTC+1, Jeremy Townson wrote:
>>
>> Hi Akka Users,
>>
>> I would like to introduce *Swakka*, a library for adding Swagger/OpenApi 
>> doc generation to akka-http. https://bitbucket.org/jtownson/swakka.
>>  
>> Like many people I was frustrated by the lack of swagger support in 
>> akka-http. After reading the proposed solutions to the problem in issue 
>> 201, "Support Rest API doc generation" (
>> https://github.com/akka/akka-http/issues/201) and trying 
>> swagger-akka-http (https://github.com/swagger-akka-http/swagger-akka-http), 
>> I decided to try a different approach.
>>
>> To briefly describe how Swakka works. One starts by instantiating an 
>> *OpenApi* case class that represent the structure of an API using 
>> Openapi/Swagger semantics. Swakka reads this API definition and generates 
>> (a) an akka-http Route reflecting the swagger structure (extracting the 
>> parameters, paths, etc in your API definition) and (b) the swagger.json 
>> itself. The akka-http Route in (a) serves the swagger.json file generated 
>> in (b) alongside your API.
>>
>> You provide nested, inner Routes as the implementations of the OpenApi 
>> endpoints. Thus you still have the full power of akka-http Directives that 
>> are not supported in Swagger.
>>
>> It's currently on bitbucket at https://bitbucket.org/jtownson/swakka. I 
>> might move it to github at some point. It's in a early alpha state, not 
>> finished, not stable and with quite a few bugs -- so not good for your work 
>> project yet. Nonetheless I am excited about the principle behind the 
>> library, so I wanted to put it out there.
>>
>> If you are willing and able to contribute to Swakka then I would be 
>> interested to hear from you. The roadmap in my mind for the next 3-6 months 
>> is
>> -- ease of use improvements
>> -- full OpenApi 2 support
>> -- bugfixes and documentation consistent with 1.0 release.
>>
>> Read more about it at https://bitbucket.org/jtownson/swakka.
>>
>> Have fun,
>> Jeremy
>>
>>

-- 
>>  Read the docs: http://akka.io/docs/
>>  Check the FAQ: 
>> http://doc.akka.io/docs/akka/current/additional/faq.html
>>  Search the archives: https://groups.google.com/group/akka-user
--- 
You received this message because you are subscribed to the Google Groups "Akka 
User List" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to akka-user+unsubscr...@googlegroups.com.
To post to this group, send email to akka-user@googlegroups.com.
Visit this group at https://groups.google.com/group/akka-user.
For more options, visit 

[akka-user] Re: Swakka - a new extension to akka-http for Swagger/OpenApi

[Jeremy Townson]

Hi Akka users,

This is an update about Swakka, an addon for generating OpenApi/Swagger 
docs with Akka-Http. I introduced Swakka in August last year. Back then it 
was new, unstable and I recommended people not to use it. 

Yesterday, I cut a v0.5 release. Whilst the library does not cover Swagger 
100%, it does cover everything in the Swagger’s famous PetstoreV2 sample. 
Therefore it should document many real world APIs.

If you are creating Akka-Http endpoints and have a need to document them, I 
recommend you check out the project at 
https://bitbucket.org/jtownson/swakka/. I hope it would help your project 
and I would be really interested to hear your feedback.

Beyond toughening up the library for a 1.0 release, I am also starting to 
consider where to go next with the project. Thoughts in my mind right now 
are
— do something completely different
— support for other documentation formats like Api Blueprint or RAML.
— having a close look at Akka-Http’s routing DSL, to see if there is a 
refactor that would yield an AST. Now that Swakka can do doc generation 
from its OpenApi case class, if it _were_ possible to generate an AST from 
a Route structure, it might also be possible to map over that to produce an 
instance of OpenApi. Akka-Http users would then have the choice of either 
coding an OpenApi instance and getting Swakka to generate Routes, or coding 
Routes and generating OpenApi. I’m not convinced this is any more than a 
dream and I do not feel I have either the knowledge or authority to go 
tinkering with one of the core abstractions in Akka-Http. But if this 
interests you, you are familiar with the Akka-Http codebase and want to 
take a punt as a pair, I’m game.

All the best,
Jeremy

On Monday, 21 August 2017 10:54:44 UTC+1, Jeremy Townson wrote:
>
> Hi Akka Users,
>
> I would like to introduce *Swakka*, a library for adding Swagger/OpenApi 
> doc generation to akka-http. https://bitbucket.org/jtownson/swakka.
>  
> Like many people I was frustrated by the lack of swagger support in 
> akka-http. After reading the proposed solutions to the problem in issue 
> 201, "Support Rest API doc generation" (
> https://github.com/akka/akka-http/issues/201) and trying 
> swagger-akka-http (https://github.com/swagger-akka-http/swagger-akka-http), 
> I decided to try a different approach.
>
> To briefly describe how Swakka works. One starts by instantiating an 
> *OpenApi* case class that represent the structure of an API using 
> Openapi/Swagger semantics. Swakka reads this API definition and generates 
> (a) an akka-http Route reflecting the swagger structure (extracting the 
> parameters, paths, etc in your API definition) and (b) the swagger.json 
> itself. The akka-http Route in (a) serves the swagger.json file generated 
> in (b) alongside your API.
>
> You provide nested, inner Routes as the implementations of the OpenApi 
> endpoints. Thus you still have the full power of akka-http Directives that 
> are not supported in Swagger.
>
> It's currently on bitbucket at https://bitbucket.org/jtownson/swakka. I 
> might move it to github at some point. It's in a early alpha state, not 
> finished, not stable and with quite a few bugs -- so not good for your work 
> project yet. Nonetheless I am excited about the principle behind the 
> library, so I wanted to put it out there.
>
> If you are willing and able to contribute to Swakka then I would be 
> interested to hear from you. The roadmap in my mind for the next 3-6 months 
> is
> -- ease of use improvements
> -- full OpenApi 2 support
> -- bugfixes and documentation consistent with 1.0 release.
>
> Read more about it at https://bitbucket.org/jtownson/swakka.
>
> Have fun,
> Jeremy
>
>

-- 
>>  Read the docs: http://akka.io/docs/
>>  Check the FAQ: 
>> http://doc.akka.io/docs/akka/current/additional/faq.html
>>  Search the archives: https://groups.google.com/group/akka-user
--- 
You received this message because you are subscribed to the Google Groups "Akka 
User List" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to akka-user+unsubscr...@googlegroups.com.
To post to this group, send email to akka-user@googlegroups.com.
Visit this group at https://groups.google.com/group/akka-user.
For more options, visit https://groups.google.com/d/optout.

[akka-user] Re: Swakka - a new extension to akka-http for Swagger/OpenApi

[Jeremy Townson]

Thank you, Martynas. I have updated the readme to include that use-case.

On Monday, 21 August 2017 10:54:44 UTC+1, Jeremy Townson wrote:
>
> Hi Akka Users,
>
> I would like to introduce *Swakka*, a library for adding Swagger/OpenApi 
> doc generation to akka-http. https://bitbucket.org/jtownson/swakka.
>  
> Like many people I was frustrated by the lack of swagger support in 
> akka-http. After reading the proposed solutions to the problem in issue 
> 201, "Support Rest API doc generation" (
> https://github.com/akka/akka-http/issues/201) and trying 
> swagger-akka-http (https://github.com/swagger-akka-http/swagger-akka-http), 
> I decided to try a different approach.
>
> To briefly describe how Swakka works. One starts by instantiating an 
> *OpenApi* case class that represent the structure of an API using 
> Openapi/Swagger semantics. Swakka reads this API definition and generates 
> (a) an akka-http Route reflecting the swagger structure (extracting the 
> parameters, paths, etc in your API definition) and (b) the swagger.json 
> itself. The akka-http Route in (a) serves the swagger.json file generated 
> in (b) alongside your API.
>
> You provide nested, inner Routes as the implementations of the OpenApi 
> endpoints. Thus you still have the full power of akka-http Directives that 
> are not supported in Swagger.
>
> It's currently on bitbucket at https://bitbucket.org/jtownson/swakka. I 
> might move it to github at some point. It's in a early alpha state, not 
> finished, not stable and with quite a few bugs -- so not good for your work 
> project yet. Nonetheless I am excited about the principle behind the 
> library, so I wanted to put it out there.
>
> If you are willing and able to contribute to Swakka then I would be 
> interested to hear from you. The roadmap in my mind for the next 3-6 months 
> is
> -- ease of use improvements
> -- full OpenApi 2 support
> -- bugfixes and documentation consistent with 1.0 release.
>
> Read more about it at https://bitbucket.org/jtownson/swakka.
>
> Have fun,
> Jeremy
>
>

-- 
>>  Read the docs: http://akka.io/docs/
>>  Check the FAQ: 
>> http://doc.akka.io/docs/akka/current/additional/faq.html
>>  Search the archives: https://groups.google.com/group/akka-user
--- 
You received this message because you are subscribed to the Google Groups "Akka 
User List" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to akka-user+unsubscr...@googlegroups.com.
To post to this group, send email to akka-user@googlegroups.com.
Visit this group at https://groups.google.com/group/akka-user.
For more options, visit https://groups.google.com/d/optout.