微服务架构实战篇(二):Spring boot2.0 + Swagger2 让你的API可视化

简介

该项目主要利用Spring boot2.0 +Swagger2 方便进行测试后台的restful形式的接口,实现动态的更新,当我们在后台的接口修改了后,swagger可以实现自动的更新,而不需要认为的维护这个接口进行测试。

  • 源码地址
    • GitHub:https://github.com/yundianzixun/spring-boot-starter-swagger2
  • 联盟公众号:IT实战联盟
  • 我们社区:https://100boot.cn

小工具一枚,欢迎使用和Star支持,如使用过程中碰到问题,可以提出Issue,我会尽力完善该Starter

版本基础

  • Spring Boot:2.0.4
  • Swagger2:2.7.0

 

操作步骤

第一步:下载SpringBoot2.0项目

  • GitHub地址:https://github.com/yundianzixun/spring-boot-starter
  • 参考文档:https://www.jianshu.com/p/7dc2240f010e

第二步:添加maven依赖

       

            io.springfox

            springfox-swagger2

            2.7.0

       

       

            io.springfox

            springfox-swagger-ui

            2.7.0

       

       

            org.apache.tomcat.embed

            tomcat-embed-jasper

       

       

       

            org.springframework.boot

            spring-boot-starter-tomcat

            provided

       

       

            org.springframework.boot

            spring-boot-starter-web

       

第三步:application.properties 增加swagger配置

#开启swagger服务

swagger.enable=true

第四步:使用注解配置Swagger

@Configuration

@EnableSwagger2

public class Swagger2Config {

    public static final String BASE_PACKAGE = "com.itunion";

    @Value("${swagger.enable}")

    private boolean enableSwagger;

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())                // 生产环境的时候关闭 swagger 比较安全

                .enable(enableSwagger)                //将Timestamp类型全部转为Long类型

                .directModelSubstitute(Timestamp.class, Long.class)                //将Date类型全部转为Long类型

                .directModelSubstitute(Date.class, Long.class)

                .select()                // 扫描接口的包路径,不要忘记改成自己的

                .apis(RequestHandlerSelectors.basePackage(BASE_PACKAGE))

                .paths(PathSelectors.any())

                .build();

    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()

            .title("Swagger RESTful APIs")

            .description("Swagger API 服务")

            .termsOfServiceUrl("http://swagger.io/")

            .contact(new Contact("Swagger", "127.0.0.1", "[email protected]"))

            .version("1.0")

            .build();

    }

 

}

 

备注

  • 正常项目上线后应该是关闭掉 swagger 的,所以这边增加了一个配置 enableSwagger
  • 可以使用 directModelSubstitute 做一些期望的类型转换

第五步:创建用户实体类UserInfo

public class UserInfo {

    @ApiModelProperty("编号")

    private Long id;

    @ApiModelProperty("用户名")

    private String userName;

    @ApiModelProperty("姓")

    private String firstName;

    @ApiModelProperty("名")

    private String lastName;

    @ApiModelProperty("邮箱")

    private String email;

    @ApiModelProperty(hidden = true)// 密码不传输

    @JsonIgnore

    private String password;

    @ApiModelProperty("状态")

    private Integer userStatus;

   /**此处省略get、set **/

 }

第六步:编写一个首页的Controller

@Api(value = "首页", description = "首页")

@RequestMapping("/")

@RestController

public class IndexController {

    @ApiOperation(value = "Hello Spring Boot", notes = "Hello Spring Boot")

    @RequestMapping(value = "/", method = RequestMethod.GET)

    public String index() {

        return "Hello Spring Boot";

    }

    @ApiOperation(value = "API 页面", notes = "接口列表")

    @RequestMapping(value = "/api", method = RequestMethod.GET)

    public void api(HttpServletResponse response) throws IOException {

        response.sendRedirect("swagger-ui.html");

    }

}

  • 为了方便访问swagger ui 页面,我们做了一个重定向 api 更方便些

第七步:编写一个登陆的Controller

@Api(value = "用户", description = "用户")

@RequestMapping("/userInfo")

@RestController

public class UserInfoController {

    @ApiOperation(value = "登录接口-多值传值方式", notes = "输入用户名和密码登录")

    @ApiResponses(value = {

            @ApiResponse(code = 200, message = "OK", response = UserInfo.class, responseContainer = "userInfo"),

            @ApiResponse(code = 405, message = "账号名或密码错误")

    })

    @ApiImplicitParam(name = "map", value = "{\"userName\":\"JackMa\",\"passWord\":\"123\"}")

    @RequestMapping(value = "loginForMap", method = RequestMethod.POST, produces= MediaType.APPLICATION_JSON_UTF8_VALUE)

    ResponseEntity loginForMap(@RequestBody Map map) {

        if (!map.get("userName").equalsIgnoreCase("JackMa") || !map.get("passWord").equalsIgnoreCase("123")) {

            return ResponseEntity.status(HttpStatus.METHOD_NOT_ALLOWED).build();

        }

        UserInfo user = new UserInfo();

        user.setId(1L);

        user.setUserName("JackMa");

        user.setFirstName("马");

        user.setLastName("云");

        user.setEmail("[email protected]");

        user.setUserStatus(1);

        return ResponseEntity.ok(user);

    }

 

    @ApiOperation(value = "登录接口-多值传输方式", notes = "输入用户名和密码登录")

    @ApiResponses(value = {

            @ApiResponse(code = 200, message = "OK", response = UserInfo.class, responseContainer = "userInfo"),

            @ApiResponse(code = 405, message = "账号名或密码错误")

    })

    @ApiImplicitParams({

            @ApiImplicitParam(name = "userName",value = "用户名", required = true, dataType = "string", paramType = "query"),

            @ApiImplicitParam(name = "passWord",value = "密码", required = true, dataType = "string",paramType = "query"),

    })

    @RequestMapping(value = "loginForParams", method = RequestMethod.POST, produces= MediaType.APPLICATION_JSON_UTF8_VALUE)

    ResponseEntity loginForMap(@RequestParam String userName, @RequestParam String passWord) {

        if (!userName.equalsIgnoreCase("JackMa") || !passWord.equalsIgnoreCase("123")) {

            return ResponseEntity.status(HttpStatus.METHOD_NOT_ALLOWED).build();

        }

        UserInfo user = new UserInfo();

        user.setId(1L);

        user.setUserName("JackMa");

        user.setFirstName("马");

        user.setLastName("云");

        user.setEmail("[email protected]");

        user.setUserStatus(1);

        return ResponseEntity.ok(user);

    }

 

}

 

备注

  • 使用Params和Param 实现了两种不同的数据传输方式
  • 建议使用Spring的 ResponseEntity 类做统一的返回结果
  • swagger 对 response code 的支持还算好,我们可以把可能出现的异常代码都一一罗列出来,方便对接的时候对异常的处理

第八步:启动运行

http://127.0.0.1:8081/api

备注

  • 端口号已自己配置为准

如下图所示:

微服务架构实战篇(二):Spring boot2.0 + Swagger2 让你的API可视化_第1张图片

swagger2.jpg

第九步:执行

微服务架构实战篇(二):Spring boot2.0 + Swagger2 让你的API可视化_第2张图片

输入.jpg

微服务架构实战篇(二):Spring boot2.0 + Swagger2 让你的API可视化_第3张图片

输出.jpg

贡献者

  • IT实战联盟-Line
  • IT实战联盟-咖啡

更多精彩内容可以关注“IT实战联盟”微信*公*众*号哦~~~

你可能感兴趣的:(互联网技术,java-web,微服务架构,架构实践)