前后端分离-利用Swagger生成接口文档

相关介绍（Swagger）

• Swagger官网

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

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

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

配置过程

源码见文章尾

pom.xml

        
            io.springfox
            springfox-swagger2
            2.7.0
        
        
            io.springfox
            springfox-swagger-ui
            2.7.0
        
        
            com.fasterxml.jackson.core
            jackson-databind
            2.9.8
        
        

配置Swagger

@Component
@EnableSwagger2
@EnableWebMvc  //必须存在
//必须存在，扫描的API Controller包
@ComponentScan(basePackages = {"com.swagger.controller"})
public class SwaggerConfig {
    @Bean
    public Docket customDocket(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());}

    private ApiInfo apiInfo(){
        Contact contact = new Contact("GodF","https://www.baidu.com","[email protected]");
        return new ApiInfoBuilder().title("GodF的API接口")
                                    .description("API接口")
                                    .contact(contact).version("1.1.0").build();
    }
}

配置WebMvc

• 用于拦截文档请求路径–swagger-ui.html
• 用于加入相关jar包

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry){
        //registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

编写接口

• 在内存中加入数据，未使用数据库

@RestController
@Api(value = "用户模块",description = "用户模块的接口信息")
public class UserController {
    //模拟数据库
    public static List users = new ArrayList<>();
    static {
        users.add(new User("张三","123456"));
        users.add(new User("李四","123456"));
    }
    //获取用户列表的方法
    @ApiOperation(value = "获取用户列表",notes = "获取所有的用户列表")
    @GetMapping("/user")
    public Object users(){
        Map map = new HashMap<>();
        map.put("users",users);
        return map;
    }
    @ApiOperation(value = "获取单个用户",notes = "根据Id查询某个用户的信息")
    @ApiImplicitParam(value = "用户Id",paramType = "path")
    @GetMapping("/user/{id}")
    public User getUserById(@PathVariable("id") int id){
        return users.get(id);
    }
    @ApiOperation(value = "添加用户",notes = "根据传入用户信息添加用户")
    @ApiImplicitParam(value = "用户对象",paramType = "query")
    @PostMapping(value = "/user")
    public Object add(User user){
        return users.add(user);
    }
    @ApiOperation(value = "删除用户",notes = "根据传入用户Id删除用户")
    @ApiImplicitParam(value = "用户Id",paramType = "path")
    @DeleteMapping("/user/{id}")
    public Object delete(@PathVariable("id") int id){
        return users.remove(id);
    }
}

查看效果

• 访问 http://localhost:8080/swagger-ui.html#/

源码

配置示例