用idea搭建一个swagger-demo

 

参考链接：微服务架构实战篇（二）：Spring boot2.0 + Swagger2 让你的API可视化

 

- 在团队开发中，一个好的 API 文档不但可以减少大量的沟通成本，还可以帮助一位新人快速上手业务。传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节，并在程序员之间代代相传。

- Swagger2 的出现就是为了从根本上解决上述问题。它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务：

    + 1.接口文档在线自动生成，文档随接口变动实时更新，节省维护成本

    + 2.支持在线接口测试，不依赖第三方工具

- Swagger 通过注解定制接口对外展示的信息，这些信息包括接口名、请求方法、参数、返回信息等。

 

新建idea项目

项目结构

第一步，pom.xml文件中引入如下swagger2的依赖

<!--maven导入Swagger,begin-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
<!--maven导入Swagger,end-->

第二步，创建swagger2配置类

docket() 方法创建Docket的Bean对象，apiInfo()则是创建ApiInfo的基本信息。

package com.example.user.myspringbootuserdemo;

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 Swagger2Config {
    @Bean
    public Docket buildDocket() {
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//调用下面apiInfo()方法
                .select()
                //Controller所在路径
                .apis(RequestHandlerSelectors.basePackage("com.example.user.myspringbootuserdemo.web"))
                .paths(PathSelectors.any())
                .build();

    }

    public ApiInfo apiInfo() {
        return  new ApiInfoBuilder()
                .title("springboot结合swagger2构建Restful API")
                .description("这是一个swagger2小型demo")
                .termsOfServiceUrl("www.baidu.com")
                .version("0.0.1")
                .build();

    }

}

所涉及到的注解及其说明

• @Api : 用在类上，说明该类的主要作用。
• @ApiOperation：用在方法上，给API增加方法说明。
• @ApiImplicitParams : 用在方法上，包含一组参数说明。
• @ApiImplicitParam：用来注解来给方法入参增加说明。

• @ApiResponses：用于表示一组响应。
• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

​          code：数字，例如400

​          message：信息，例如"请求参数没填好"

        ​ response：抛出异常的类

• @ApiModel：用在返回对象类上，描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
• ​ @ApiModelProperty：描述一个model的属性

 

给实体类中的属性添加解释说明，在属性上面加@ApiModelProperty注解

或者是在web层的的方法上面使用@ApiImplicitParams注解，来备注属性说明，但这样描述在参数过多的条件下会比较麻烦。

在web层的的方法上面使用@ApiImplicitParams注解，来备注属性说明显示字体会加粗

在conteroller用@RequestBody包裹请求对象类型显示如下：

@ApiOperation(value = "创建User实例",notes = "创建User实例")
    @ApiImplicitParam(name = "user",value = "用户详情实体类",required = true,dataType = "User")
    @PostMapping("/user")
    public User post(@RequestBody User user){

        return userService.save(user);
    }

第四步，web--conteroller层

使用@ApiOperation(value = "查询全部用户",notes = "默认根据升序查询全部用户信息")，来解释说明方法

@ApiModel 接收对象传参

注意： 在后台采用类对象接收参数时，Swagger自带的工具采用的是JSON传参， 测试时需要在参数上加入@RequestBody,正常运行采用form或URL提交时候请删除。

 

启动项目

测试登录，打开浏览器输入：http://localhost:8080/swagger-ui.html

 

 

==================================================================

和配置类对应关系

填入参数测试：

在conteroller不写明数据类型显示如下：

在conteroller用@RequestBody包裹请求对象类型显示如下：

如果再application.yml中做了修改：

打开浏览器输入：http://localhost:8280//kafka-cmt/v1/swagger-ui.html

 

参考链接：

https://blog.csdn.net/qq_35193093/article/details/80075043

 

https://www.jianshu.com/p/a0caf58b3653