SpringBoot学习笔记:Swagger实现文档管理



  • SpringBoot学习笔记:Swagger实现文档管理

    Swagger

    Swagger是一个规范且完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务。Swagger的目标是对REST API定义一个标准且和语言无关的接口,可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力

    集成Swagger管理API文档

    项目中集成Swagger

    首先是添加swagger的依赖:

    <!--swagger-spring-boot-starter -->
    <dependency>
       <groupId>com.spring4all</groupId>
       <artifactId>swagger-spring-boot-starter</artifactId>
       <version>1.9.0.RELEASE</version>
    </dependency>
    

    接着,在启动类中添加@EnableSwagger2Doc注解开启Swagger,如下:

    @EnableSwagger2Doc
    @SpringBootApplication
    public class Application {
    
       public static void main(String[] args) {
           SpringApplication.run(CodeHelperApplication.class, args);
       }
    }
    

    使用Swagger生成文档

    Swagger通过注解来生成对应的API,在接口上我们需要加上各种注解来描述这个接口,如

       @ApiOperation(value = " 查找城镇列表 ")
       @ApiResponses({@ApiResponse(code = 200,message = "OK",response = String.class)})
       @RequestMapping(value = "getTownInfoList.do", method = RequestMethod.POST)
       public List<String> getTownInfoList() {
           try {
               return studentMapper.getListGroup("stu_town");
           } catch (Exception e) {
               e.printStackTrace();
           }
           return null;
       }
    

    在这里我们使用到了两个注解:

    在线测试接口

    通过 服务器地址:port/swagger-ui.html 来访问Swagger服务,其界面如下:

    找到刚刚描述的方法,可以查看接口详情,以及尝试接口调用。

    Swagger注解

    本节主要描述一些常用的生成接口文档的注解,上面介绍过的就不说了

    @Api

    用在类上,说明该类的作用.

    @Api(tags = {"学生信息接口"})
    @RestController
    public class StudentController {
     ...  
    }
    

    @ApiModel

    用在类上,表示对参数类进行说明。

    @ApiModel(value = "com.ms.qiandao.model.StudentModel",description = "新增用户参数")
    public class StudentModel {
       private Integer stu_id;
       private String stu_name;
       private String stu_sex;
       ...  
    }
    

    @ApiModedlProperty

    用在字段上,表示对参数类中的字段进行说明。

    @ApiModel(value = "com.ms.qiandao.model.StudentModel",description = "新增用户参数")
    public class StudentModel {
       @ApiModelProperty(value = "学生ID")
       private Integer stu_id;
       @ApiModelProperty(value = "学生姓名")
       private String stu_name;
       @ApiModelProperty(value = "学生性别")
       private String stu_sex;
       ...  
    }
    

    @ApiParam

    用于对Controller方法中的参数进行说明。

    @RequestMapping("cancel.do")
    public RegisterCode getById(@ApiParam(value = "学生id",required = true) Integer id) {
      ...
    }
    

    @ApilmplicitParam和@ApilmplicitParams

    用于方法上,为单独的请求参数进行说明,和@ApiParam差不多,只不过是写在方法上面

    参考资料

    来自:https://www.cnblogs.com/MrSaver/p/11546403.html


Log in to reply
 

最新帖子

推荐阅读