精华内容
下载资源
问答
  • swagger

    千次阅读 2019-06-11 11:12:31
    本文作者:小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119  实际项目中非常需要写文档,提高Java...一:Swagger介绍Swagger是当前最好用的Restful API文档生成的...

      实际项目中非常需要写文档,提高Java服务端和Web前端以及移动端的对接效率。
      听说Swagger这个工具,还不错,就网上找了些资料,自己实践了下。

    一:Swagger介绍

    Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目

    实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档,

    同时swagger-ui还可以测试spring restful风格的接口功能。


    官方网站为:http://swagger.io/


    中文网站:http://www.sosoapi.com


    二:Swagger与Spring MVC集成步骤

    1.Maven关键配置

            
    
      
    1. <dependency>
    2. <groupId>com.mangofactory </groupId>
    3. <artifactId>swagger-springmvc </artifactId>
    4. <version>1.0.2 </version>
    5. </dependency>
    6. <dependency>
    7. <groupId>org.springframework </groupId>
    8. <artifactId>spring-webmvc </artifactId>
    9. <version>4.1.6.RELEASE </version>
    10. </dependency>


    2. 插件配置
       CustomJavaPluginConfig

    3.复制swagger的相关js等静态资源到webapp目录。
       swagger-ui.js之类的。
       我copy过一次,但是有问题,最后从网上下载了一个项目,可以直接用的那种。
       然后自己再逐步改造。

    4.启动项目



    三、常见swagger注解一览与使用
    最常用的5个注解

    @Api:修饰整个类,描述Controller的作用

    @ApiOperation:描述一个类的一个方法,或者说一个接口

    @ApiParam:单个参数描述


    @ApiModel:用对象来接收参数

    @ApiProperty:用对象接收参数时,描述对象的一个字段


    其它若干

    @ApiResponse:HTTP响应其中1个描述

    @ApiResponses:HTTP响应整体描述


    @ApiClass

    @ApiError

    @ApiErrors


    @ApiParamImplicit

    @ApiParamsImplicit


    四、关键代码和实际例子
        例子1:
       
    
       
    1. @ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    2. @ResponseBody
    3. @RequestMapping(value = "list", method = RequestMethod.POST)
    4. public Result<User> list(
    5. @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
    6. @ApiParam(value = "token", required = true) @RequestParam String token) {
    7. Result<User> result = new Result<User>();
    8. User user = new User();
    9. result.setData(user);
    10. return result;
    11. }


       @ApiParam(value = "token", required = true) @RequestParam String token
    Web前端/移动端HTTP请求方式:直接把参数附带到URL后面,或者用AJAX方法,表单提交。

      例子2:
    
      
    1. @ApiOperation(value = "update用户", notes = ")", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    2. @ResponseBody
    3. @RequestMapping(value = "update", method = RequestMethod.GET /*,produces = MediaType.APPLICATION_FORM_URLENCODED_VALUE*/)
    4. public Result<String> update(User user) {
    5. String u = findUser(user);
    6. System.out.println(u);
    7. return null;
    8. }


     当参数太多的时候,需要定义太多的参数,排版看起来很不舒服。
    这个时候,可以使用对象来接收。
    @ApiModel(value = "用户对象",description="user2") 
    public class User extends CommonParam{

    }
    Web前端/移动端HTTP请求方式:直接把参数附带到URL后面,或者用AJAX方法,表单提交。
    这里面存在一个小问题,当后端用对象User来接收参数的时候,Swagger自带的工具是这样的:
     
    这种形式,并不是表单提交,或者把参数附加到URL的后面。
    我们只能手动构造URL,附带参数去提交。
    如果需要测试的话!

    例子3:
    
       
    1. public Result<String> add(@RequestBody User user) {
    2. String u = findUser(user);
    3. System.out.println(u);
    4. return null;
    5. }


    Web前端/移动端HTTP请求方式:必须把参数,放到request请求的body中去。
    后端不能直接用request.getParam("token")这种。

    获得request body中的数据,手动转换成目标数据。
        String charReader(HttpServletRequest request) throws IOException {

            BufferedReader br = request.getReader();

            String str, wholeStr = "";
            while ((str = br.readLine()) != null) {
                wholeStr += str;
            }
            return wholeStr;

        }

    个人推荐
    1.参数不多的时候,用例子1,用@ApiParam注解生成文档。
      swagger可视化界面,可以直接设置参数,发送请求来测试
    2.参数比较多的时候,用例子2,用对象来接收参数,在对象里针对每个字段,@ApiModelProperty注解生成文档。
       swagger可视化界面,可以直接设置参数,但是无法接收到。
      因此,推荐使用其它HTTP请求或POST模拟工具,发送请求,模拟测试。

    不推荐例子3,不通用,局限性比较大。


    五、若干截图
     

    六、源代码
    
       
    1. package cn.fansunion.swagger.serverapi.controller;
    2. import org.springframework.http.MediaType;
    3. import org.springframework.stereotype.Controller;
    4. import org.springframework.web.bind.annotation.RequestBody;
    5. import org.springframework.web.bind.annotation.RequestMapping;
    6. import org.springframework.web.bind.annotation.RequestMethod;
    7. import org.springframework.web.bind.annotation.RequestParam;
    8. import org.springframework.web.bind.annotation.ResponseBody;
    9. import com.wordnik.swagger.annotations.Api;
    10. import com.wordnik.swagger.annotations.ApiOperation;
    11. import com.wordnik.swagger.annotations.ApiParam;
    12. /**
    13. * 小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
    14. * 博客:http://blog.csdn.net/fansunion
    15. *
    16. */
    17. @Api(value = "user", description = "用户管理", produces = MediaType.APPLICATION_JSON_VALUE)
    18. @Controller
    19. @RequestMapping( "user")
    20. public class UserController {
    21. // 列出某个类目的所有规格
    22. @ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    23. @ResponseBody
    24. @RequestMapping(value = "list", method = RequestMethod.POST)
    25. public Result<User> list(
    26. @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
    27. @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId2,
    28. @ApiParam(value = "token", required = true) @RequestParam String token) {
    29. Result<User> result = new Result<User>();
    30. User user = new User();
    31. result.setData(user);
    32. return result;
    33. }
    34. @ApiOperation(value = "添加用户", notes = "获取商品信息(用于数据同步)", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    35. @ResponseBody
    36. @RequestMapping(value = "add", method = RequestMethod.POST)
    37. // @RequestBody只能有1个
    38. // 使用了@RequestBody,不能在拦截器中,获得流中的数据,再json转换,拦截器中,也不清楚数据的类型,无法转换成java对象
    39. // 只能手动调用方法
    40. public Result<String> add(@RequestBody User user) {
    41. String u = findUser(user);
    42. System.out.println(u);
    43. return null;
    44. }
    45. @ApiOperation(value = "update用户", notes = "获取商品信息(用于数据同步)", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    46. @ResponseBody
    47. @RequestMapping(value = "update", method = RequestMethod.GET)
    48. public Result<String> update(User user) {
    49. String u = findUser(user);
    50. System.out.println(u);
    51. return null;
    52. }
    53. private String findUser(User user) {
    54. String token = user.getToken();
    55. return token;
    56. }
    57. }


    
       
    1. package cn.fansunion.swagger.serverapi.controller;
    2. import com.wordnik.swagger.annotations.ApiModel;
    3. import com.wordnik.swagger.annotations.ApiModelProperty;
    4. /**
    5. * 小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
    6. * 博客:http://blog.csdn.net/fansunion
    7. *
    8. */
    9. @ApiModel(value = "用户对象", description = "user2")
    10. public class User extends CommonParam {
    11. @ApiModelProperty(value = "商品信息", required = true)
    12. private String name;
    13. @ApiModelProperty(value = "密码", required = true)
    14. private String password;
    15. @ApiModelProperty(value = "性别")
    16. private Integer sex;
    17. @ApiModelProperty(value = "密码", required = true)
    18. private String token;
    19. public String getToken() {
    20. return token;
    21. }
    22. public void setToken(String token) {
    23. this.token = token;
    24. }
    25. public String getName() {
    26. return name;
    27. }
    28. public void setName(String name) {
    29. this.name = name;
    30. }
    31. public String getPassword() {
    32. return password;
    33. }
    34. public void setPassword(String password) {
    35. this.password = password;
    36. }
    37. public Integer getSex() {
    38. return sex;
    39. }
    40. public void setSex(Integer sex) {
    41. this.sex = sex;
    42. }
    43. }

    
       
    1. package cn.fansunion.swagger.serverapi.swagger;
    2. import org.springframework.beans.factory.annotation.Autowired;
    3. import org.springframework.context.annotation.Bean;
    4. import org.springframework.context.annotation.Configuration;
    5. import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
    6. import org.springframework.web.servlet.config.annotation.EnableWebMvc;
    7. import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
    8. import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
    9. import com.mangofactory.swagger.models.dto.ApiInfo;
    10. import com.mangofactory.swagger.paths.SwaggerPathProvider;
    11. import com.mangofactory.swagger.plugin.EnableSwagger;
    12. import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
    13. @Configuration
    14. @EnableWebMvc
    15. @EnableSwagger
    16. public class CustomJavaPluginConfig extends WebMvcConfigurerAdapter {
    17. private SpringSwaggerConfig springSwaggerConfig;
    18. @Autowired
    19. public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
    20. this.springSwaggerConfig = springSwaggerConfig;
    21. }
    22. /**
    23. * 链式编程 来定制API样式 后续会加上分组信息
    24. *
    25. * @return
    26. */
    27. @Bean
    28. public SwaggerSpringMvcPlugin customImplementation() {
    29. return new SwaggerSpringMvcPlugin( this.springSwaggerConfig)
    30. .apiInfo(apiInfo()).includePatterns( ".*")
    31. .useDefaultResponseMessages( false)
    32. // .pathProvider(new GtPaths())
    33. .apiVersion( "0.1").swaggerGroup( "user");
    34. }
    35. private ApiInfo apiInfo() {
    36. ApiInfo apiInfo = new ApiInfo( "小雷移动端API接口平台",
    37. "提供详细的后台所有Restful接口", "http://blog.csdn.net/FansUnion",
    38. "FansUnion@qq.com", "小雷博客", "http://blog.csdn.net/FansUnion");
    39. return apiInfo;
    40. }
    41. @Override
    42. public void configureDefaultServletHandling(
    43. DefaultServletHandlerConfigurer configurer) {
    44. configurer.enable();
    45. }
    46. class GtPaths extends SwaggerPathProvider {
    47. @Override
    48. protected String applicationPath() {
    49. return "/restapi";
    50. }
    51. @Override
    52. protected String getDocumentationPath() {
    53. return "/restapi";
    54. }
    55. }
    56. }

    七、项目下载地址

    八、参考资料

      实际项目中非常需要写文档,提高Java服务端和Web前端以及移动端的对接效率。
      听说Swagger这个工具,还不错,就网上找了些资料,自己实践了下。

    一:Swagger介绍

    Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目

    实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档,

    同时swagger-ui还可以测试spring restful风格的接口功能。


    官方网站为:http://swagger.io/


    中文网站:http://www.sosoapi.com


    二:Swagger与Spring MVC集成步骤

    1.Maven关键配置

            
    
      
    1. <dependency>
    2. <groupId>com.mangofactory </groupId>
    3. <artifactId>swagger-springmvc </artifactId>
    4. <version>1.0.2 </version>
    5. </dependency>
    6. <dependency>
    7. <groupId>org.springframework </groupId>
    8. <artifactId>spring-webmvc </artifactId>
    9. <version>4.1.6.RELEASE </version>
    10. </dependency>


    2. 插件配置
       CustomJavaPluginConfig

    3.复制swagger的相关js等静态资源到webapp目录。
       swagger-ui.js之类的。
       我copy过一次,但是有问题,最后从网上下载了一个项目,可以直接用的那种。
       然后自己再逐步改造。

    4.启动项目



    三、常见swagger注解一览与使用
    最常用的5个注解

    @Api:修饰整个类,描述Controller的作用

    @ApiOperation:描述一个类的一个方法,或者说一个接口

    @ApiParam:单个参数描述


    @ApiModel:用对象来接收参数

    @ApiProperty:用对象接收参数时,描述对象的一个字段


    其它若干

    @ApiResponse:HTTP响应其中1个描述

    @ApiResponses:HTTP响应整体描述


    @ApiClass

    @ApiError

    @ApiErrors


    @ApiParamImplicit

    @ApiParamsImplicit


    四、关键代码和实际例子
        例子1:
       
    
       
    1. @ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    2. @ResponseBody
    3. @RequestMapping(value = "list", method = RequestMethod.POST)
    4. public Result<User> list(
    5. @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
    6. @ApiParam(value = "token", required = true) @RequestParam String token) {
    7. Result<User> result = new Result<User>();
    8. User user = new User();
    9. result.setData(user);
    10. return result;
    11. }


       @ApiParam(value = "token", required = true) @RequestParam String token
    Web前端/移动端HTTP请求方式:直接把参数附带到URL后面,或者用AJAX方法,表单提交。

      例子2:
    
      
    1. @ApiOperation(value = "update用户", notes = ")", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    2. @ResponseBody
    3. @RequestMapping(value = "update", method = RequestMethod.GET /*,produces = MediaType.APPLICATION_FORM_URLENCODED_VALUE*/)
    4. public Result<String> update(User user) {
    5. String u = findUser(user);
    6. System.out.println(u);
    7. return null;
    8. }


     当参数太多的时候,需要定义太多的参数,排版看起来很不舒服。
    这个时候,可以使用对象来接收。
    @ApiModel(value = "用户对象",description="user2") 
    public class User extends CommonParam{

    }
    Web前端/移动端HTTP请求方式:直接把参数附带到URL后面,或者用AJAX方法,表单提交。
    这里面存在一个小问题,当后端用对象User来接收参数的时候,Swagger自带的工具是这样的:
     
    这种形式,并不是表单提交,或者把参数附加到URL的后面。
    我们只能手动构造URL,附带参数去提交。
    如果需要测试的话!

    例子3:
    
       
    1. public Result<String> add(@RequestBody User user) {
    2. String u = findUser(user);
    3. System.out.println(u);
    4. return null;
    5. }


    Web前端/移动端HTTP请求方式:必须把参数,放到request请求的body中去。
    后端不能直接用request.getParam("token")这种。

    获得request body中的数据,手动转换成目标数据。
        String charReader(HttpServletRequest request) throws IOException {

            BufferedReader br = request.getReader();

            String str, wholeStr = "";
            while ((str = br.readLine()) != null) {
                wholeStr += str;
            }
            return wholeStr;

        }

    个人推荐
    1.参数不多的时候,用例子1,用@ApiParam注解生成文档。
      swagger可视化界面,可以直接设置参数,发送请求来测试
    2.参数比较多的时候,用例子2,用对象来接收参数,在对象里针对每个字段,@ApiModelProperty注解生成文档。
       swagger可视化界面,可以直接设置参数,但是无法接收到。
      因此,推荐使用其它HTTP请求或POST模拟工具,发送请求,模拟测试。

    不推荐例子3,不通用,局限性比较大。


    五、若干截图
     

    六、源代码
    
       
    1. package cn.fansunion.swagger.serverapi.controller;
    2. import org.springframework.http.MediaType;
    3. import org.springframework.stereotype.Controller;
    4. import org.springframework.web.bind.annotation.RequestBody;
    5. import org.springframework.web.bind.annotation.RequestMapping;
    6. import org.springframework.web.bind.annotation.RequestMethod;
    7. import org.springframework.web.bind.annotation.RequestParam;
    8. import org.springframework.web.bind.annotation.ResponseBody;
    9. import com.wordnik.swagger.annotations.Api;
    10. import com.wordnik.swagger.annotations.ApiOperation;
    11. import com.wordnik.swagger.annotations.ApiParam;
    12. /**
    13. * 小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
    14. * 博客:http://blog.csdn.net/fansunion
    15. *
    16. */
    17. @Api(value = "user", description = "用户管理", produces = MediaType.APPLICATION_JSON_VALUE)
    18. @Controller
    19. @RequestMapping( "user")
    20. public class UserController {
    21. // 列出某个类目的所有规格
    22. @ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    23. @ResponseBody
    24. @RequestMapping(value = "list", method = RequestMethod.POST)
    25. public Result<User> list(
    26. @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
    27. @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId2,
    28. @ApiParam(value = "token", required = true) @RequestParam String token) {
    29. Result<User> result = new Result<User>();
    30. User user = new User();
    31. result.setData(user);
    32. return result;
    33. }
    34. @ApiOperation(value = "添加用户", notes = "获取商品信息(用于数据同步)", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    35. @ResponseBody
    36. @RequestMapping(value = "add", method = RequestMethod.POST)
    37. // @RequestBody只能有1个
    38. // 使用了@RequestBody,不能在拦截器中,获得流中的数据,再json转换,拦截器中,也不清楚数据的类型,无法转换成java对象
    39. // 只能手动调用方法
    40. public Result<String> add(@RequestBody User user) {
    41. String u = findUser(user);
    42. System.out.println(u);
    43. return null;
    44. }
    45. @ApiOperation(value = "update用户", notes = "获取商品信息(用于数据同步)", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    46. @ResponseBody
    47. @RequestMapping(value = "update", method = RequestMethod.GET)
    48. public Result<String> update(User user) {
    49. String u = findUser(user);
    50. System.out.println(u);
    51. return null;
    52. }
    53. private String findUser(User user) {
    54. String token = user.getToken();
    55. return token;
    56. }
    57. }


    
       
    1. package cn.fansunion.swagger.serverapi.controller;
    2. import com.wordnik.swagger.annotations.ApiModel;
    3. import com.wordnik.swagger.annotations.ApiModelProperty;
    4. /**
    5. * 小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
    6. * 博客:http://blog.csdn.net/fansunion
    7. *
    8. */
    9. @ApiModel(value = "用户对象", description = "user2")
    10. public class User extends CommonParam {
    11. @ApiModelProperty(value = "商品信息", required = true)
    12. private String name;
    13. @ApiModelProperty(value = "密码", required = true)
    14. private String password;
    15. @ApiModelProperty(value = "性别")
    16. private Integer sex;
    17. @ApiModelProperty(value = "密码", required = true)
    18. private String token;
    19. public String getToken() {
    20. return token;
    21. }
    22. public void setToken(String token) {
    23. this.token = token;
    24. }
    25. public String getName() {
    26. return name;
    27. }
    28. public void setName(String name) {
    29. this.name = name;
    30. }
    31. public String getPassword() {
    32. return password;
    33. }
    34. public void setPassword(String password) {
    35. this.password = password;
    36. }
    37. public Integer getSex() {
    38. return sex;
    39. }
    40. public void setSex(Integer sex) {
    41. this.sex = sex;
    42. }
    43. }

    
       
    1. package cn.fansunion.swagger.serverapi.swagger;
    2. import org.springframework.beans.factory.annotation.Autowired;
    3. import org.springframework.context.annotation.Bean;
    4. import org.springframework.context.annotation.Configuration;
    5. import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
    6. import org.springframework.web.servlet.config.annotation.EnableWebMvc;
    7. import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
    8. import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
    9. import com.mangofactory.swagger.models.dto.ApiInfo;
    10. import com.mangofactory.swagger.paths.SwaggerPathProvider;
    11. import com.mangofactory.swagger.plugin.EnableSwagger;
    12. import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
    13. @Configuration
    14. @EnableWebMvc
    15. @EnableSwagger
    16. public class CustomJavaPluginConfig extends WebMvcConfigurerAdapter {
    17. private SpringSwaggerConfig springSwaggerConfig;
    18. @Autowired
    19. public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
    20. this.springSwaggerConfig = springSwaggerConfig;
    21. }
    22. /**
    23. * 链式编程 来定制API样式 后续会加上分组信息
    24. *
    25. * @return
    26. */
    27. @Bean
    28. public SwaggerSpringMvcPlugin customImplementation() {
    29. return new SwaggerSpringMvcPlugin( this.springSwaggerConfig)
    30. .apiInfo(apiInfo()).includePatterns( ".*")
    31. .useDefaultResponseMessages( false)
    32. // .pathProvider(new GtPaths())
    33. .apiVersion( "0.1").swaggerGroup( "user");
    34. }
    35. private ApiInfo apiInfo() {
    36. ApiInfo apiInfo = new ApiInfo( "小雷移动端API接口平台",
    37. "提供详细的后台所有Restful接口", "http://blog.csdn.net/FansUnion",
    38. "FansUnion@qq.com", "小雷博客", "http://blog.csdn.net/FansUnion");
    39. return apiInfo;
    40. }
    41. @Override
    42. public void configureDefaultServletHandling(
    43. DefaultServletHandlerConfigurer configurer) {
    44. configurer.enable();
    45. }
    46. class GtPaths extends SwaggerPathProvider {
    47. @Override
    48. protected String applicationPath() {
    49. return "/restapi";
    50. }
    51. @Override
    52. protected String getDocumentationPath() {
    53. return "/restapi";
    54. }
    55. }
    56. }

    七、项目下载地址

    八、参考资料
    展开全文
  • Swagger

    千次阅读 2020-05-26 09:28:29
    目录1、Swagger简介2、SpringBoot集成Swagger3、配置Swagger4、配置扫描接口 1、Swagger简介 前后端分离 前端 -> 前端控制层、视图层 后端 -> 后端控制层、服务层、数据访问层 前后端通过API进行交互 ...

    1、Swagger简介

    前后端分离

    • 前端 -> 前端控制层、视图层

    • 后端 -> 后端控制层、服务层、数据访问层

    • 前后端通过API进行交互

    • 前后端相对独立且松耦合

    产生的问题

    • 前后端集成,前端或者后端无法做到“及时协商,尽早解决”,最终导致问题集中爆发。

    解决方案

    • 首先定义schema [ 计划的提纲 ],并实时跟踪最新的API,降低集成风险

    Swagger

    • 号称世界上最流行的API框架

    • Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新

    • 直接运行,在线测试API

    • 支持多种语言 (如:Java,PHP等)

    • 官网:https://swagger.io/

    2、SpringBoot集成Swagger

    SpringBoot集成Swagger => springfox,两个jar包

    • Springfox-swagger2

    • swagger-springmvc

    使用Swagger

    要求:jdk 1.8 + 否则swagger2无法运行

    步骤:

    1、新建一个SpringBoot-web项目

    2、添加Maven依赖

    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
    <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
    </dependency>
    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.9.2</version>
    </dependency>
    

    3、编写HelloController,测试确保运行成功!

    4、要使用Swagger,我们需要编写一个配置类-SwaggerConfig来配置 Swagger

    @Configuration //配置类
    @EnableSwagger2// 开启Swagger2的自动配置
    public class SwaggerConfig {  
    }
    

    5、访问测试 :http://localhost:8080/swagger-ui.html ,可以看到swagger的界面;
    在这里插入图片描述

    3、配置Swagger

    1、Swagger实例Bean是Docket,所以通过配置Docket实例来配置Swaggger。

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
       return new Docket(DocumentationType.SWAGGER_2);
    }
    

    2、可以通过apiInfo()属性配置文档信息

    //配置文档信息
    private ApiInfo apiInfo() {
       Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
       return new ApiInfo(
               "Swagger学习", // 标题
               "学习演示如何配置Swagger", // 描述
               "v1.0", // 版本
               "http://terms.service.url/组织链接", // 组织链接
               contact, // 联系人信息
               "Apach 2.0 许可", // 许可
               "许可链接", // 许可连接
               new ArrayList<>()// 扩展
      );
    }
    

    演示:

    //配置了Swagger信息=apiInfo
        private ApiInfo apiInfo(){
    
            Contact contact = new Contact("一叶孤舟","https://www.csdn.net/","517394441@qq.com");
    
            return new ApiInfo(
                    "一叶孤舟的SwaggerAPI文档",
                    "你要悄悄拔尖,然后惊艳所有人",
                    "v1.0",
                    "urn:tos",
                    contact,
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LICENSE-2.0",
                    new ArrayList());
        }
    

    3、Docket 实例关联上 apiInfo()

    @Bean
    public Docket docket() {
       return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    

    4、重启项目,访问测试 http://localhost:8080/swagger-ui.html 看下效果;
    在这里插入图片描述

    4、配置扫描接口

    1、构建Docket时通过select()方法配置怎么扫描接口。

    @Bean
    public Docket docket() {
       return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
          .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
          .build();
    }
    

    2、重启项目测试,由于我们配置根据包的路径扫描接口,所以我们只能看到一个类

    3、除了通过包路径配置扫描接口外,还可以通过配置其他方式扫描接口,这里注释一下所有的配置方式:

    any() // 扫描所有,项目中的所有接口都会被扫描到
    none() // 不扫描接口
    // 通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
    withMethodAnnotation(final Class<? extends Annotation> annotation)
    // 通过类上的注解扫描,如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
    withClassAnnotation(final Class<? extends Annotation> annotation)
    basePackage(final String basePackage) // 根据包路径扫描接口
    

    4、除此之外,我们还可以配置接口扫描过滤:

    @Bean
    public Docket docket() {
       return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
          .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
           // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
          .paths(PathSelectors.ant("/kuang/**"))
          .build();
    }
    

    5、这里的可选值还有
    any() // 任何请求都扫描
    none() // 任何请求都不扫描
    regex(final String pathRegex) // 通过正则表达式控制
    ant(final String antPattern) // 通过ant()控制
    在这里插入图片描述

    5、配置Swagger开关

    1、通过enable()方法配置是否启用swagger,如果是false,swagger将不能在浏览器中访问了。

    @Bean
    public Docket docket() {
       return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .enable(false) //配置是否启用Swagger,如果是false,在浏览器将无法访问
          .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
          .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
           // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
          .paths(PathSelectors.ant("/kuang/**"))
          .build();
    }
    

    效果:
    在这里插入图片描述
    2、如何动态配置当项目处于test、dev环境时显示swagger,处于prod时不显示?

    @Bean
    public Docket docket(Environment environment) {
       // 设置要显示swagger的环境
       Profiles of = Profiles.of("dev", "test");
       // 判断当前是否处于该环境
       // 通过 enable() 接收此参数判断是否要显示
       boolean b = environment.acceptsProfiles(of);
       
       return new Docket(DocumentationType.SWAGGER_2)
          .apiInfo(apiInfo())
          .enable(b) //配置是否启用Swagger,如果是false,在浏览器将无法访问
          .select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
          .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
           // 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口
          .paths(PathSelectors.ant("/kuang/**"))
          .build();
    }
    

    6、配置API分组

    1、如果没有配置分组,默认是default。通过groupName()方法即可配置分组:

    @Bean
    public Docket docket(Environment environment) {
       return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
          .groupName("hello") // 配置分组
           // 省略配置....
    }
    

    2、重启项目查看分组

    3、如何配置多个分组?配置多个分组只需要配置多个docket即可:

    @Bean
    public Docket docket1(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
    }
    @Bean
    public Docket docket2(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }
    @Bean
    public Docket docket3(){
       return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
    }
    

    4、重启项目查看即可
    在这里插入图片描述

    7、实体配置

    1、新建一个实体类

    @ApiModel("用户实体")
    public class User {
       @ApiModelProperty("用户名")
       public String username;
       @ApiModelProperty("密码")
       public String password;
    }
    

    2、只要这个实体在请求接口的返回值上(即使是泛型),都能映射到实体项中:

    @RequestMapping("/getUser")
    public User getUser(){
       return new User();
    }
    

    3、重启查看测试
    在这里插入图片描述
    注:并不是因为@ApiModel这个注解让实体显示在这里了,而是只要出现在接口方法的返回值上的实体都会显示在这里,而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

    @ApiModel为类添加注释

    @ApiModelProperty为类属性添加注释

    8、常用注解

    Swagger的所有注解定义在io.swagger.annotations包下

    下面列一些经常用到的,未列举出来的可以另行查阅说明:
    Swagger注解 简单说明
    @Api(tags = “xxx模块说明”) 作用在模块类上
    @ApiOperation(“xxx接口说明”) 作用在接口方法上
    @ApiModel(“xxxPOJO说明”) 作用在模型类上:如VO、BO
    @ApiModelProperty(value = “xxx属性说明”,hidden = true) 作用在类方法和属性上,hidden设置为true可以隐藏该属性
    @ApiParam(“xxx参数说明”) 作用在参数、方法和字段上,类似@ApiModelProperty

    我们也可以给请求的接口配置一些注释

    @ApiOperation("狂神的接口")
    @PostMapping("/kuang")
    @ResponseBody
    public String kuang(@ApiParam("这个名字会被返回")String username){
       return username;
    }
    

    这样的话,可以给一些比较难理解的属性或者接口,增加一些配置信息,让人更容易阅读!

    相较于传统的Postman或Curl方式测试接口,使用swagger简直就是傻瓜式操作,不需要额外说明文档(写得好本身就是文档)而且更不容易出错,只需要录入数据然后点击Execute,如果再配合自动化框架,可以说基本就不需要人为操作了。

    Swagger是个优秀的工具,现在国内已经有很多的中小型互联网公司都在使用它,相较于传统的要先出Word接口文档再测试的方式,显然这样也更符合现在的快速迭代开发行情。当然了,提醒下大家在正式环境要记得关闭Swagger,一来出于安全考虑二来也可以节省运行时内存。

    展开全文
  • swagger 介绍及两种使用方法

    万次阅读 多人点赞 2018-04-26 15:13:30
    一:swagger是什么? 1、是一款让你更好的书写API文档的规范且完整框架。 2、提供描述、生产、消费和可视化RESTful Web Service。 3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库...

    一:swagger是什么?

    1、是一款让你更好的书写API文档规范且完整的框架。

    2、提供描述、生产、消费和可视化RESTful Web Service。

    3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

    方法一:使用第三方依赖(最简单的方法)

    1、在pom.xml文件中添加第三方swagger依赖()

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

    2、在Spring Boot项目的启动类上添加@EnableSwagger2Doc注解,就可以直接使用啦。
    3、https://github.com/SpringForAll/spring-boot-starter-swagger这是GitHub上这个swagger依赖实现的项目,里面有详细的讲解。

    方法二:使用官方依赖

    1、在pom.xml文件中添加swagger相关依赖
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.7.0</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.7.0</version>
            </dependency>
    
    第一个是API获取的包,第二是官方给出的一个ui界面。这个界面可以自定义,默认是官方的,对于安全问题,以及ui路由设置需要着重思考。
    2、swagger的configuration

    需要特别注意的是swagger scan base package,这是扫描注解的配置,即你的API接口位置。

    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2
    public class Swagger2 {
    
            @Bean
            public Docket createRestApi() {
                return new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo())
                        .select()
                        .apis(RequestHandlerSelectors.basePackage("com.yss.ms.admin"))
                        .paths(PathSelectors.any())
                        .build();
            }
    
            private ApiInfo apiInfo() {
                return new ApiInfoBuilder()
                        .title("服务:发布为daocke镜像,权限管理,用户管理,页面管理,日志 后台 APIs")
                        .description("服务:发布为daocke镜像,权限管理,用户管理,页面管理,日志 后台")
                        .termsOfServiceUrl("http://192.168.1.198:10070/platformgroup/ms-admin")
                        .contact("程序猿")
                        .version("1.0")
                        .build();
            }
    
        }
    

    三、具体使用

    1、在API上做一些声明
    //本controller的功能描述
    @Api(value = "pet", description = "the pet API")
    public interface PetApi {
    
        //option的value的内容是这个method的描述,notes是详细描述,response是最终返回的json model。其他可以忽略
        @ApiOperation(value = "Add a new pet to the store", notes = "", response = Void.class, authorizations = {
            @Authorization(value = "petstore_auth", scopes = {
                @AuthorizationScope(scope = "write:pets", description = "modify pets in your account"),
                @AuthorizationScope(scope = "read:pets", description = "read your pets")
                })
        }, tags={ "pet", })
    
        //这里是显示你可能返回的http状态,以及原因。比如404 not found, 303 see other
        @ApiResponses(value = { 
            @ApiResponse(code = 405, message = "Invalid input", response = Void.class) })
        @RequestMapping(value = "/pet",
            produces = { "application/xml", "application/json" }, 
            consumes = { "application/json", "application/xml" },
            method = RequestMethod.POST)
        ResponseEntity<Void> addPet(
        //这里是针对每个参数的描述
        @ApiParam(value = "Pet object that needs to be added to the store" ,required=true ) @RequestBody Pet body);
    
    2、设定访问API doc的路由

    在配置文件中,application.yml中声明:

    springfox.documentation.swagger.v2.path: /api-docs
    

    这个path就是json的访问request mapping.可以自定义,防止与自身代码冲突。

    API doc的显示路由是:http://localhost:8080/swagger-ui.html

    如果项目是一个webservice,通常设定home / 指向这里:

    @Controller
    public class HomeController {
    
        @RequestMapping(value = "/swagger")
        public String index() {
            System.out.println("swagger-ui.html");
            return "redirect:swagger-ui.html";
        }
    }
    

    四:swagger的常用API

    1、api标记

    Api 用在类上,说明该类的作用。可以标记一个Controller类做为swagger 文档资源,使用方式:

    @Api(value = "/user", description = "Operations about user")

    在这里插入图片描述

    2、ApiOperation标记

    ApiOperation:用在方法上,说明方法的作用,每一个url资源的定义,使用方式:

    @ApiOperation(
              value = "Find purchase order by ID",
              notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
              response = Order,
              tags = {"Pet Store"})
    

    [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-V8AEIZ2l-1609508640724)(http://ozpb6wow8.bkt.clouddn.com/22.png)]

    3、ApiParam标记

    ApiParam请求属性,使用方式:

    public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)
    

    [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-5veQGqo7-1609508640725)(http://ozpb6wow8.bkt.clouddn.com/3.png)]

    4、ApiResponse

    ApiResponse:响应配置,使用方式:
    @ApiResponse(code = 400, message = "Invalid user supplied")
    [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-6nd1sH5D-1609508640729)(http://ozpb6wow8.bkt.clouddn.com/44.png)]

    5、ApiResponses

    ApiResponses:响应集配置,使用方式:
    @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
    [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-SNlJ6vSI-1609508640730)(http://ozpb6wow8.bkt.clouddn.com/5.png)]

    6、ResponseHeader

    响应头设置,使用方法
    @ResponseHeader(name="head1",description="response head conf")
    [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-NDXgB4JA-1609508640731)(http://ozpb6wow8.bkt.clouddn.com/6.png)]

    展开全文
  • Swagger注解-@ApiModel 和 @ApiModelProperty

    万次阅读 多人点赞 2019-04-27 11:41:32
    在实体类上边使用,标记类时swagger的解析类 概述 提供有关swagger模型的其它信息,类将在操作中用作类型时自动内省 属性 属性名称 数据类型 默认值 说明 value String 类名 为模型提供备用名称 ...

    Swagger注解-@Api
    Swagger注解-@ApiOperation
    Swagger注解-@ApiImplicitParams 和 @ApiImplicitParam
    Swagger注解-@ApiModel 和 @ApiModelProperty
    Swagger注解-@ApiResponses 和 @ApiResponse
    Swagger注解-@ResponseHeader
    Swagger注解-@ApiParam
    Swagger注解-@Authorization 和 @AuthorizationScope
    Swagger注解-@SwaggerDefinition
    Swagger注解-@ExternalDocs
    Springboot 集成 Swagger GitHub 地址


    @ApiModel

    使用场景

    在实体类上边使用,标记类时swagger的解析类

    概述

    提供有关swagger模型的其它信息,类将在操作中用作类型时自动内省

    属性

    属性名称数据类型默认值说明
    valueString类名为模型提供备用名称
    descriptionString“”提供详细的类描述
    parentClass<?> parentVoid.class为模型提供父类以允许描述继承关系
    discriminatoryString“”支持模型继承和多态,使用鉴别器的字段的名称,可以断言需要使用哪个子类型
    subTypesClass<?>[]{}从此模型继承的子类型数组
    referenceString“”指定对应类型定义的引用,覆盖指定的任何其他元数据

    @ApiModelProperty

    使用场景

    使用在被 @ApiModel 注解的模型类的属性上

    概述

    添加和操作模型属性的数据

    属性

    属性名称数据类型默认值说明
    valueString“”属性简要说明
    nameString“”运行覆盖属性的名称。重写属性名称
    allowableValuesString“”限制参数可接收的值,三种方法,固定取值,固定范围
    accessString“”过滤属性,参阅:io.swagger.core.filter.SwaggerSpecFilter
    notesString“”目前尚未使用
    dataTypeString“”参数的数据类型,可以是类名或原始数据类型,此值将覆盖从类属性读取的数据类型
    requiredbooleanfalse是否为必传参数,false:非必传参数; true:必传参数
    positionint0允许在模型中显示排序属性
    hiddenbooleanfalse隐藏模型属性,false:不隐藏; true:隐藏
    exampleString“”属性的示例值
    readOnlybooleanfalse指定模型属性为只读,false:非只读; true:只读
    referenceString“”指定对应类型定义的引用,覆盖指定的任何其他元数据
    allowEmptyValuebooleanfalse允许传空值,false:不允许传空值; true:允许传空值

    Swagger注解-@Api
    Swagger注解-@ApiOperation
    Swagger注解-@ApiImplicitParams 和 @ApiImplicitParam
    Swagger注解-@ApiModel 和 @ApiModelProperty
    Swagger注解-@ApiResponses 和 @ApiResponse
    Swagger注解-@ResponseHeader
    Swagger注解-@ApiParam
    Swagger注解-@Authorization 和 @AuthorizationScope
    Swagger注解-@SwaggerDefinition
    Swagger注解-@ExternalDocs
    Springboot 集成 Swagger GitHub 地址


    展开全文
  • Swagger使用指南

    万次阅读 多人点赞 2018-06-03 11:39:09
    1:认识Swagger Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端...
  • Swagger 常用注解使用详解

    万次阅读 多人点赞 2018-03-16 09:18:24
    在集成了swagger2后,找了半天的原因,发现使用@ApiImplicitParam这个注解可以解决这个问题。对应下面的参数。所以我们可以使用这个注解来解决我们所遇到的参考为空的问题。而且已经集成了swagger2,所以我们尽量...
  • 5分钟了解swagger

    万次阅读 多人点赞 2017-08-27 20:47:06
    API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架。其他API文档工具没有API文档工具之前,大家都是手写API文档的,在什么地方书写的都有,有在confl
  • Swagger简介

    万次阅读 多人点赞 2015-03-22 21:09:05
    前言 Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。...Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视...
  • Swagger 教程

    万次阅读 2021-01-02 14:49:26
    SpringBoot与Swagger2整合 依赖: <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> &...
  • swagger2 注解说明 ( @ApiImplicitParams )

    万次阅读 多人点赞 2018-10-17 12:25:36
    @Api:用在请求的类上,表示对类的说明 tags="说明该类的作用,可以在UI界面上看到的注解" value="该参数没什么意义,在UI界面上也看到,所以不需要配置" @ApiOperation:用在请求的方法上,说明方法的用途、...
  • swagger2Demo,swagger

    2018-07-06 12:27:04
    swagger2Demo,swagger,这个是写的一个demo,用于调试接口swagger确实好用,jdk1.8的,欢迎下载,
  • swagger_java_swagger_源码

    2021-09-30 17:56:40
    swagger与springboot的集成
  • Swagger 使用

    2017-11-28 16:25:27
    .Net Swagger Api Demo .Net Swagger Api Demo .Net Swagger Api Demo
  • 如果项目已经集成了swagger,只需要在pom.xml添加,如果你的项目没有集成swagger,自行百度或看最下方的链接 swagger-bootstrap-ui是Swagger的前端UI实现,目的是替换Swagger默认的UI实现Swagger-UI,使文档更友好...
  • swagger Demo

    2018-02-06 15:33:38
    Swagger简单Demo例子,Swagger简单Demo例子,Swagger简单Demo例子
  • server.port=8081
  • Swagger UI

    2016-12-04 19:05:06
    Swagger UI
  • swagger-editor、swagger-ui和swaggerui( tomca)版,windows x64 nodejs安装版项目包下载
  • Swagger教程

    万次阅读 多人点赞 2018-08-15 20:16:35
    Swagger搭建Restful接口教程一 一、前言  Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件,随着现在许多公司实现了前后端分离,swagger越来越受欢迎了。  博主之前在网上查看相关博客的时候,...

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 84,344
精华内容 33,737
关键字:

Swagger