Swagger注解生成Rest Api文档 并生成静态文档

Swagger注解生成Rest Api文档

1、添加配置类

@Configuration //spring boot配置注解
@EnableSwagger2 //启用swagger2功能注解
public class Swagger2Config extends WebMvcConfigurationSupport {
    @Bean
    public Docket createRestfulApi() {//api文档实例
        return new Docket(DocumentationType.SWAGGER_2)//文档类型：DocumentationType.SWAGGER_2
                .apiInfo(apiInfo())//api信息
                .select()//构建api选择器
                .apis(RequestHandlerSelectors.basePackage("com.topplus.vite.controller"))//api选择器选择api的包
                .paths(PathSelectors.any())//api选择器选择包路径下任何api显示在文档中
                .build();//创建文档
    }

    private ApiInfo apiInfo() {//接口的相关信息
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful接口")
                .description("测试接口描述")
                .termsOfServiceUrl("termsOfServiceUrl")
                .contact("foo") //.contact(new Contact("xxx", "http://www.baidu.com","[email protected]"))// 联系
                .version("1.0")
                .license("testLicenseInfo")
                .licenseUrl("http://springfox.github.io/springfox/docs/current/")
                .build();
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

2、maven依赖

io.springfox
springfox-swagger2
2.6.1



io.springfox
springfox-swagger-ui
2.6.1

3、在controller加注解

示例：

@Api(value="TransportRecordAPI",tags={"TransportRecordAPI"})//接口简要标注
@RestController
@RequestMapping(value = {"api/vehicle", "backstage/vehicle"}, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public class TransportRecordController {
@Autowired
private TransportRecordService transportRecordService;

@ApiImplicitParams({
@ApiImplicitParam(paramType = "header", name = "Token", value = "token", dataType = "String", required = true,defaultValue = "123")})
//接口功能描述
@ApiOperation(value = "上传综合交通参数接口")
@PostMapping("uploadTransport")
public Object uploadTransport(@RequestBody(required = false)TransportRecordEntity transportRecordEntity) {
return transportRecordService.recordSave(transportRecordEntity);

}

}

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数描述

@ApiModel：用对象来接收参数

@ApiProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiParamImplicitL：一个请求参数

@ApiParamsImplicit 多个请求参数

完成以上就可以启动项目然后访问。

• http://localhost:8080/swagger-ui.html#/ 访问api文档
• http://localhost:8080/v2/api-docs 访问json数据，这个接下来生成静态文档会用到

##================分割线====================#

4、使用Swagger2Markup生成静态文档

在pom文件中添加插件

    io.github.swagger2markup
    swagger2markup-maven-plugin
    1.3.1
    
        
        http://localhost:8080/v2/api-docs
        
        src/docs/asciidoc/generated/all
        
        
        
            
           CONFLUENCE_MARKUP
            
            
            
            MARKDOWN

            TAGS
        
    

使用方法：在Maven 中找到该插件运行它

5、效果图

markdown格式文档