Swagger下的RESTFUL风格微服务

前言

本文在上一篇的基础上修改的，文章地址：【RESTFUL 风格微服务开发笔记】，所以这篇文章主要记录的是使用方式。

简单描述一下Swagger UI与 Springfox Swagger：
Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

Springfox Swagger: Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。

关键词：Swagger；Swagger UI；微服务；

依赖包

<!--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>

开发实例

本文在上一篇的基础上修改的，文章地址：RESTFUL 风格微服务开发笔记

Controller

@Api(tags="ItemsEditController",description="商品编辑微服务(增删改操作)")
@RestController
public class ItemsController {

    @Autowired
    private ItemService service;

    @ApiOperation("查找所有商品")
    @RequestMapping(value = {"/selectAllItems"},method = RequestMethod.GET)//查询
    public List<Items> selectAllItems() {
        return service.seleceAllItems();
    }

    @ApiOperation("删除商品")
    @RequestMapping(value = {"/deleteByPrimaryKey/{id}"},method = RequestMethod.DELETE)//删除
    public RespBean deleteByPrimaryKey(@PathVariable Integer id) {
        try {
            service.deleteByPrimaryKey(id);
            return RespBean.success(200,"删除成功");
        } catch (Exception e) {
            e.printStackTrace();
            return RespBean.success(500,"删除失败");
        }
    }

    @ApiOperation("插入商品")
    @RequestMapping(value = {"/insert"},method = RequestMethod.POST)//创建
    public RespBean insert(@RequestBody @ApiParam("商品对象") Items items) {

        try {
            System.out.println(items.toString());
            service.insert(items);
            return RespBean.success(200,"添加成功",items);
        } catch (Exception e) {
            e.printStackTrace();
            return RespBean.success(500,"添加失败");
        }
    }

    @ApiOperation("查找商品")
    @RequestMapping(value = {"/selectByPrimaryKey/{id}"},method = RequestMethod.GET)//查询
    public Items selectByPrimaryKey(@PathVariable Integer id) {
        return service.selectByPrimaryKey(id);
    }

    @ApiOperation("修改商品")
    @RequestMapping(value = {"/updateByPrimaryKey"},method = RequestMethod.PUT)//修改
    public RespBean updateByPrimaryKey(@RequestBody @ApiParam("商品对象") Items items) {
        try {
            System.out.println(items.toString());
            service.updateByPrimaryKey(items);
            return RespBean.success(200,"修改成功",items);
        } catch (Exception e) {
            e.printStackTrace();
            return RespBean.success(500,"修改失败");
        }
    }
}

Swagger 配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("org.web.controller"))
                //为有@Api注解的Controller生成API文档
                //.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }
    //配置Swagger API描述
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SwaggerUI演示")
                .description("商品编辑微服务")
                .contact("不会脱发的羊")
                .version("1.0")
                .build();
    }
}

Swagger 测试

在Tomcat环境下运行项目，浏览器地址栏输入：http://localhost:8080/swagger-ui.html（Swagger提供的），可以看到如下页面：
通过代码内文字描述与页面的显示状态，可以很轻松得到以下注解的作用。

常用注解：

• @Api()用于类；
  描述这个类是swagger的资源
• @ApiOperation()用于方法；
  描述一个http请求的操作
• @ApiParam()用于方法，参数，字段说明；
  描述参数的添加元数据（说明或是否必填等）
• @ApiModel()用于类
  表示对类进行说明，用于参数用实体类接收
• @ApiModelProperty()用于方法，字段
  表示对model属性的说明或者数据操作更改
• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法
  表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

更多注解使用方式见博文：【Swagger 常用注解使用详解】