Do you suffer from projects that have no documentation? Are you struggling to document your projects? Have you been victimized by disrepair documents? Boy, eat my amway! By deploying Swagger, these problems will be removed from your elegant, readable, testable, time-sensitive document. Don’t you want to try?

Results show

Without further ado, let’s get straight to the end result, black feed the dog!

Step1. Add comments to interfaces

Step2. View the Json structure automatically generated according to the comment

Step3. Automatically generate documents according to the Json structure

Step4. Interface call tests can be performed through documents

The cause of

As a developer, writing documentation is a real pain in the neck, and the main pain points are as follows (in my opinion) :

  • Separate from the development effort, the documentation process requires switching between documentation and code. Inefficient.
  • After logical updates to the code, there is another place to update the documentation. trouble
  • The code has been fully commented and needs to be retranslated into documentation. Repeat work

In fact, to sum up, a word – lazy.

Based on the above points, I started to think, is there any tool that can automatically generate documents based on comments? If so, you can reduce the time spent developing and producing documents, avoid rework, and ensure that the documents are available (they fall into disrepair).

Swagger is introduced

First, the official definition

Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.

To put it simply, Swagger is actually a description specification of an interface. As long as the interface is described and annotated according to this specification, structured data can be produced, and then exquisite interface documents can be produced by using the tools provided by Swagger officially. So the ‘Deploy Swagger’ mentioned in the introduction is, to be precise, the’ deploy Swagger specification ‘.

Document Generation Roadmap

The deployment of

  • The SDK was introduced into the project

      composer require zircote/swagger-php
Copy the code

  • Adding comments to interfaces

    After introduction, you can directly add comments to the interface according to the SDK specification, for example: swagger-php-example

    To provide a simple example, take the Laravel/Lumen framework as an example. php namespace App\Http\Controllers; use Illuminate\Http\Request; Class ExampleController extends Controller {/** * this is an API that needs to be implemented ** This is the basic description of the project. @swg \Swagger(* schemes={" HTTP "}, * host="somehost.webdev.com", * basePath="/ API ", * @ SWG \ Info (* title = "this is a test project," * version = "1.0.0", * @swg \Contact(* email="[email protected]" *) *) *) * * * summary=" here is the interface description ", * Produces ={"application/json"}, * Parameter 1 * @swg \Parameter(* description=" page number ", * in="query", * name="pageNum", * type="number", * required=true *), * Parameter 2 * @swg \Parameter(* description=" page content number", * in="query", * name="pageSize", * type="number" *), * Response body * @swg \Response(* Response =200, * description="Success", * // You can also add examples of returned data, @swg \Response(* Response =404, * description="Not Found", *) *) */ public function getSomeThing(Request $Request) {Copy the code

    Copying the above example, we now have an interface with standard structure annotations.

  • Constructing the call interface

    After the annotation is constructed, the next step is to produce Swagger standard data. Here we choose Json as the output structure.

    For convenience, we package the logic to get Json data as an interface, so that we can get the standard Swagger Json anytime, anywhere. Take Laravel/Lumen framework as an example, a simple example is as follows:

    <? php namespace App\Http\Controllers; Class SwaggerController extends Controller {public function getSwaggerJson() {public function getSwaggerJson() { $swagger = \Swagger\scan([' directory to scan 1', 'directory to scan 2',... ); return response()->json($swagger, 200); }}Copy the code

    Another official Json data is provided for reference: official reference

    At this point, standard Swagger Json can be obtained through this interface, and then it is a matter of data presentation.

  • Interface Document Presentation

    At first, I came up with the idea of building the swagger-UI provided by the government into a service and providing a unified entrance. Later, I felt that this method was too limited to check documents anytime and anywhere and record the service address.

    I wondered if I could use a Chrome plugin to do this. Research, as expected, there are predecessors to go this way, there are already ready-made plug-ins can be used.

    Swagger – UI plug-in

    After the plug-in is installed, as shown at the beginning of the article, click to open the Swagger-UI plug-in on the interface page to get the document and perform interface tests.

    At this point, a simple, efficient Swagger environment is set up, specific how to use, it depends on your preferences. Hope you enjoy it!

Reference documents

Swagger-php SDK

If you need swagger-UI, you can build your own Swagger-UI

Swagger website

Swagger standard parameter description

Swagger OpenAPI specification