SpringBoot项目中使用Swagger2和Spring rest docs 生成Rest API 文档


先看怎么生成在线文档
引入Swagger2的依赖

<!--swagger相关-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-bean-validators</artifactId>
            <version>${springfox.version}</version>
        </dependency>

当然也要引入相关的spring-boot-starter,包括test。
定义一个Swagger Config:

@Configuration
@EnableSwagger2
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {
    @Bean
    public Docket restApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .securitySchemes(asList(
                        new OAuth(
                                "petstore_auth",
                                asList(new AuthorizationScope("write_pets", "modify pets in your account"),
                                        new AuthorizationScope("read_pets", "read your pets")),
                                singletonList(new ImplicitGrant(new LoginEndpoint("http://petstore.swagger.io/api/oauth/dialog"), "tokenName"))
                        ),
                        new ApiKey("api_key", "api_key", "header")
                ))
                .select()
                .apis(RequestHandlerSelectors.basePackage("head.swagger2markup.controller"))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Petstore API")
                .description("Petstore API在线文档")
                .contact(new Contact("head", null, "452228391@qq.com"))
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .version("1.0.0")
                .build();
    }
}

注意一定要加上@EnableSwagger2注解表示启用Swagger2。它的作用是定义Api的overview部分,title、description、contact等等。然后生成一个Docket,定义了需要扫描的API包路径,还加入了安全验证,这里提供了OAuth和ApiKey两种方式,这部分还没好好研究,等以后有时间再看。

然后在代码中加入swagger的注解以提供相关说明信息,比如:
在这里插入图片描述
以Api开头的注解就是swagger相关注解,在类、方法、参数上都有对应注解以提供说明信息,具体代码可看完整实例代码

这时访问 http://localhost:8080/swagger-ui.html 就能看到在线文档了,提供了api说明和model实体类说明,点击try it out 还能进行在线测试。
在这里插入图片描述
Swagger2还提供了对JSR303验证的支持,比如

 @Size(min = 1, max = 100)
    private String name;

引入

		<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-bean-validators</artifactId>
            <version>${springfox.version}</version>
        </dependency>

在SwaggerConfig上加入@Import(BeanValidatorPluginsConfiguration.class),即可在文档中看到相关约束,效果如下
在这里插入图片描述
接下来是离线文档,比如html和pdf格式,spring官方文档就是基于这种格式(asciidoc)。

说一下主要思路,详细代码看完整示例
swagger提供了一个url:http://localhost:8080/v2/api-docs ,返回了所有api的信息。

  • 读取这个url,将结果存储到swagger.json。
    @Test
    public void createSpringfoxSwaggerJson() throws Exception {
//        String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
        String outputDir = "target/swagger";
        MvcResult result = mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andReturn();

        MockHttpServletResponse response = result.getResponse();
        String swaggerJson = response.getContentAsString();
        Files.createDirectories(Paths.get(outputDir));
        try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)) {
            writer.write(swaggerJson);
        }
    }
  • 利用swagger2markup-maven-plugin插件读取swagger.json,生成一系列adoc文件。
  • 写一个index.adoc文件,这个文件的内容基本是固定的。
    include::{generated}/overview.adoc[] include::manual_content1.adoc[] include::manual_content2.adoc[] include::{generated}/paths.adoc[] include::{generated}/security.adoc[] include::{generated}/definitions.adoc[]
    它就是用来包含上一步生成的adoc文件的,其中manual_content1.adoc和manual_content2.adoc是自定义的,采用asciidoc格式,manual_content1.adoc如下
    == 自定义章节 1
    
    This is some dummy text
    
    === 子章节
    
    Dummy text of sub chapter
    
  • 最后利用asciidoctor-maven-plugin插件将index.adoc文件转成html或pdf。

最终效果如下:
在这里插入图片描述

此时各个API是没有请求和响应示例的,需要用到spring-restdocs生成的snippets。snippets就是一段代码示例,通过springMvc Test生成。swagger2markup-maven-plugin 会将生成的snippets添加到adoc文件中。

步骤如下:
加入依赖:

		<dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-mockmvc</artifactId>
        </dependency>

测试代码中添加对api的测试,比如这里测试addPet

@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "target/asciidoc/snippets")
@SpringBootTest
@RunWith(SpringRunner.class)
public class Swagger2MarkupTest {
    @Autowired
    private MockMvc mockMvc;

    @Test
    public void addANewPetToTheStore() throws Exception {
        this.mockMvc.perform(post("/pets/").content(createPet())
                .contentType(MediaType.APPLICATION_JSON))
                .andDo(document("addPetUsingPOST", preprocessResponse(prettyPrint())))
                .andExpect(status().isOk());
    }

document方法就是生成这个api对应的snippet。

最后mvn clean test,因为插件都是绑定到test上的,当然你可以绑定到其他生命周期。

效果如下:
在这里插入图片描述
可以看到请求和响应示例已经添加到最终的文档中了。
well,it’s done.

©️2020 CSDN 皮肤主题: 大白 设计师:CSDN官方博客 返回首页