2:Spring Boot 使用Swagger2 快速生成Restful API


1.pom

  • 工程中引入下面依赖
    <!--引入Swagger组件 -->
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.8.0</version>
    </dependency>

    <!--SwaggerUI界面-->
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.8.0</version>
    </dependency>

2.配置Conf类

    //开启Swagger2
    @EnableSwagger2
    //boot 配置类
    @Configuration
    public class Swagger2Config {
    
        /**
         * 通过 createRestApi函数来构建一个DocketBean
         */
        @Bean
        public Docket createRestApi() {
    
            return new Docket(DocumentationType.SWAGGER_2)
                    //调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容
                    .apiInfo(apiInfo())
                    .select()
                    /**
                     * 控制暴露出去的路径下的实例
                     * 如果某个接口不想暴露,可以使用以下注解
                     * @ApiIgnore 这样,该接口就不会暴露在 swagger2 的页面下
                     */
                    .apis(RequestHandlerSelectors.basePackage("org.ko.web.rest"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        /**
         * 构建API文档详细参数
         * @return
         */
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Swagger2 API")
                    .contact(new Contact("K.O", "", ""))    //作者
                    .version("1.0")
                    .description("API 描述")
                    .build();
        }
    }

3.Controller使用Swagger注解, 配置文档

    @RestController
    @RequestMapping("/user")
    //配置Swagger 接口组注释
    @Api(value = "UserController", description = "用户集成接口")
    public class UserController {
    
        @Autowired private UserService userService;
    
        @PostMapping
        //单个方法注释
        @ApiOperation("新增用户")
        public Long save(
                //参数注释
                @ApiParam(name = "user", value = "用户数据", required = true) @RequestBody User user) {
            return userService.save(user);
        }
    }

4.Swagger注解解释

  • @Api: 用在类上, 说明该类的作用
    @Api(value = "UserController", description = "用户集成接口")
  • @ApiOperation: 用在方法上, 说明方法的作用
    @ApiOperation(value = "新增用户", notes = "新增用户", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
  • @ApiImplicitParams: 用在方法上, 包含一组参数说明
  • @ApiImplicitParams: 用在@ApiImplicitParams注解中, 指定一个请求参数的各个方面
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "主键", required = true, dataType = "Long", paramType = "path")
    })
  • @ApiParam: 用在方法参数上, 表示当前参数作用
    @ApiParam(name = "user", value = "用户数据", required = true)
  • @ApiResponses: 用在方法上, 表示当前方法的一组响应
  • @ApiResponse: 用在@ApiResponses注解中, 用来表示一个错误响应信息
    @ApiResponses({
            @ApiResponse(code = 400, message = "User doesn't exist")
    })
  • @ApiModel: 用在实体类上, 用来表示一个实体
    @ApiModel
    public class User {}
  • @ApiModelProperty: 用在实体类的属性上, 翻译属性
    //类属性注释
    @ApiModelProperty(value = "id", name = "主键ID")
    private Long id;

    @ApiModelProperty(value = "name", name = "姓名")
    private String name;

    @ApiModelProperty(value = "age", name = "年龄")
    private Short age;

5.访问

Swagger UI: http://localhost:8080/swagger-ui.html

6.Demo
GitHub: Spring Boot 使用Swagger2 快速生成RESTful API

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
平台声明:文章内容(如有图片或视频亦包括在内)由作者上传并发布,文章内容仅代表作者本人观点,简书系信息发布平台,仅提供信息存储服务。

推荐阅读更多精彩内容

  • Android 自定义View的各种姿势1 Activity的显示之ViewRootImpl详解 Activity...
    passiontim阅读 173,596评论 25 708
  • 需求: 为客户端同事写接口文档的各位后端同学,已经在各种场合回忆了使用自动化文档工具前手写文档的血泪史.我的故事却...
    _Lyux阅读 4,733评论 0 2
  • Spring Boot 参考指南 介绍 转载自:https://www.gitbook.com/book/qbgb...
    毛宇鹏阅读 46,974评论 6 342
  • 〈十〉 坤仪殿 皇后端坐在青金瑞兽雕漆凤椅上,穿一件明黄色会客展衣,梳一个只有皇后能梳的凌云髻,神情庄重严肃,头上...
    君清兮阅读 297评论 1 1
  • 1、结构| | 定义表格| | 定义表格标题。| | 定义表格的表头。| | 定义表格的行。| ...
    一Left一阅读 741评论 0 0