github.com/thetreep/go-swagger@v0.0.0-20240223100711-35af64f14f01/docs/about.md (about)

     1  # Approaches to API development
     2  
     3  There are essentially two ways along which your API and its documentation tend to evolve.
     4  This toolkit aims to support you along both and remove the repetitive nature of writing what is essentially boilerplate code for faster iteration times.
     5  
     6  ## Design first approach
     7  The first one is an artifact of that first meeting where you hash out what your service will do.
     8  Hopefully you've come up with some document that services as a kind of contract for what the affected people and teams will need to do.
     9  
    10  At this stage you probably want to be able to generate a server, perhaps a client to talk to that server.
    11  
    12  Most likely, you want to have your front-end team use mock data for that server, while the back-end team
    13  is working on their part of the application.
    14  
    15  This is the **design first** approach for swagger.
    16  
    17  ## Code first approach
    18  Now we're moving on to the second iteration of the project and at this stage, there might be a design meeting for the
    19  new features, or they might just be refinements of the previous APIs. When no changes are required to the contract,
    20  all is great because people can keep doing what they were doing and everybody is happy.
    21  
    22  However it might be that some change is required for the front-end, let's say they need a boolean added to some model
    23  because they want to display an "accepted-terms-and-conditions" checkbox.
    24  
    25  The back-end can decide to add this to the code, provide the necessary annotation and regenerate the swagger
    26  specification document.
    27  
    28  This is the **code first** approach for swagger.
    29  
    30  ## The toolkit
    31  This toolkit supports both ways.
    32  
    33  It tries to do so while staying as close as possible to the go stdlib interfaces, it tries to have no opinions
    34  besides the fact that documentation is important.
    35  
    36  It tries to integrate well with the rest of the go ecosystem as well as the swagger ecosystem.
    37  
    38  A series of contrib projects will add higher level optional functionality so that you can use the generated code with
    39  confidence whether your application is your personal blog or the next AWS.