Swagger2自动生成api文档

目录

1. swagger2是什么?

  1为什么要写文档？

  2. 接口文档(接口注释) 有什么作用？

2. 使用Springboot整合Swagger2

3.swagger2常用注解  

---

1. swagger2是什么?

——swagger是一个RESTFUL 接口的文档在线自动生成和功能测试的框架 

           可以将项目内的所有接口controller生成一个文档

      说白了就是：

        就是网站连接地址 连接用来调controller中的方法的

        Controller中被外部用户所调用的方法 就叫做接口

  1为什么要写文档？

        节省时间，更方便

  2. 接口文档(接口注释) 有什么作用？

      接口文档指的是当前方法的返回值有什么样的状态码；

      需要写清楚这个状态码(401) 代表的含义和需要传什么样的参数

         原因是项目是前后端分离的，写前端的人员会根据接口对应的状态码跳弹窗，所以需要知道每个状态码代表的意思，随之写后端的人员需要写接口文档。

2. 使用Springboot整合Swagger2

   1.创建springboot项目
   2.在pom.xml中添加依赖

       <!-- Swagger API文档 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

3.添加Swagger2配置类SwaggerConfig
     1：修改扫描包名
     2：启动类依次加上注解

@SpringBootApplication
@MapperScan("com.zking.swaggerdemo.mapper")
@EnableSwagger2
@ComponentScan("com.zking.swaggerdemo.utils")

 4.API接口编写

 

 5.SpringBoot启动成功后，访问 http://localhost:8080/swagger-ui.html 即可

（将8080改成自己的端口号）

成功后的网页效果图： 

3.swagger2常用注解  

注解	作用
@Api	用在类上，说明该类的作用
@ApiOperation	注解来给API增加方法说明
@ApiImplicitParams	用在方法上包含一组参数说明
@ApiImplicitParam	用来注解来给方法入参增加说明
@ApiResponses	用于表示一组响应
@ApiResponse	用在@ApiResponses中，一般用于表达一个错误的响应信息
@ApiModel	描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty	描述一个model的属性
@ApiResponse参数	code：数字，如400 message：信息，如“参数填写错误” response：抛出异常的类 @ApiImplicitParam参数： paramTpye：指定参数放在哪些地方（header/query/path/body/form） name：参数名 dataTpye：参数类型 required：是否必输（true/false） value：说明参数的意思 defaultValue：参数默认值