Http通信协议接口接入swagger步骤实现自动生成接口文档

Posted 2021-01-05 nuonuozhou

步骤如下：

1、将framework-server版本号由1.5.5升级至1.5.6：
<framework-server.version>1.5.6</framework-server.version>
2、在application.properties添加以下配置：
#是否开启swagger生产环境需要设置为false
swagger.enable = true
#swagger api-docs版本号
swagger.api.info.version = 1.0.0
#swagger api-docs标题
swagger.api.info.title = framework-example api文档
#swagger扫描annotation包路径，该路径要包含接口和实体类
swagger.resource.package = com.meitong.framework.server.example
3、将接口和实体类以及接口入参添加swagger相关注解，示例如下：
接口：
@Path("/restResource")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@Api(value = "Rest resource operations")
public interface RestResource {

    @GET
    @Path("/invokeGet/{id}/{name}")
    @ApiOperation(value = "invokeGet示例", notes = "invokeGet说明", response = List.class, httpMethod = "GET")
    List<String> invokeGet(@PathParam("id") Integer id, @PathParam("name") String name);

    /**
     * invokePost method
     *
     * @param ids
     * @return List<String>
     */
    @POST
    @Path("/invokePost")
    @ApiOperation(value = "invokePost示例", notes = "invokePost说明", response = List.class, httpMethod = "POST")
    List<String> invokePost(List<Integer> ids);

    @PUT
    @Path("/invokePut")
    @ApiOperation(value = "invokePut示例", notes = "invokePut说明", response = Void.class, httpMethod = "PUT")
    void invokePut(List<String> names);

    @DELETE
    @Path("/invokeDelete/{id}")
    @ApiOperation(value = "invokeDelete示例", notes = "invokeDelete说明", response = Void.class, httpMethod = "DELETE")
    void invokeDelete(@PathParam("id") Integer id);

    @GET
    @Path("/getAllUser")
    @ApiOperation(value = "获取所有的用户",notes = "使用说明",response = User.class,responseContainer = "List",httpMethod = "GET")
    List<User> getAllUser();

    @POST
    @Path("/insert")
    @ApiOperation(value = "新增用户",notes = "使用说明",response = Void.class,httpMethod = "POST")
    void insert(@ApiParam(value = "用户信息",name = "user",required = true) User user);
}
实体类：
@ApiModel(description = "用户信息")
public class User {

    @ApiModelProperty(value = "用户名",required = true)
    private String userName;
    @ApiModelProperty(value = "用户ID",required = true)
    private String userId;

    //get and set
}
4.接口文档访问：
 http://ip:port/swagger.json
5.完成系统接入以后，将步骤4生成的接口文档地址汇总发到我这边。我需要将这些接口集成到swagger-ui中
6.swagger-ui访问地址
http://101.37.117.177:8080/static/#/

 

如果集成到swagger-ui中会存在跨域请求问题，所以需要添加一个全局的过滤器:

com.meitong.framework.server.filters.CORSFilter