Swagger | 手把手带你写自动生成接口文档的爽感(零基础亲测实用)

目录

背景

学习上的计划

pox.xml

yaml 配置文件

config 层

controller 层

访问路径

效果图

导出 Word文档

添加依赖

找到生成出的网站Json接口

在启动类中添加方法

---

背景

最近做了一个项目发现，提交项目时，接口文档没写，完全没时间写接口文档了太多了，而且还容易漏写，我该如何快速写出文档并且让项目经理眼前一亮呢？欸！还真有！！Swagger技术，接口文档生成工具！！

官网：API Documentation & Design Tools for Teams | Swagger

学习上的计划

• 如何导出成word文档

话不多说直接上实战！！！！

pox.xml

        org.springdoc
        springdoc-openapi-ui
        1.6.11

yaml 配置文件

spring:
  mvc:
    static-path-pattern: /**
    pathmatch:
      matching-strategy: ant_path_matcher
springdoc:
  swagger-ui:
    path: /swagger-ui.html

config 层

package com.jkglxt.www.config;


import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;


@Configuration
@EnableWebSecurity
public class SwaggerConfig extends WebSecurityConfigurerAdapter {


    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
                .authorizeRequests()
                .antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll() // 允许访问Swagger UI和API文档
                .anyRequest().authenticated()
                .and()
                .formLogin().permitAll()
                .and()
                .logout().permitAll();
    }
}

controller 层

@RestController
@Tag(name = "DailyScoreController", description = "控制器功能介绍")
public class DailyScoreController {

    // 添加/修改记录
    @GetMapping("/addorupdateScore")
    @Operation(
            summary = "接口的大概描述",
            description = "接口详细描述",
            responses = {
                    @ApiResponse(
                            responseCode = "状态码",
                            description = "状态码的说明",
                            content = @Content(schema = @Schema(implementation = String.class))
                    )
            }
    )
    public int addScore(DailyScore dailyScore) {
        System.out.println("添加/修改记录"+dailyScore);
        System.out.println("该死的用户传过来的 添加的的记录"+dailyScore);
        return dailyScoreService.addScore(dailyScore);
    }
    // 控制器接口....省略
}

访问路径

http://localhost:8080/swagger-ui/index.html 

效果图

导出 Word文档

添加依赖

        org.apache.poi
        poi-ooxml
        5.2.2

找到生成出的网站Json接口

http://localhost:8080/v3/api-docs

在启动类中添加方法

这里要实现接口先 implements CommandLineRunner 

package com.jkglxt.www;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.client.RestTemplate;
import org.apache.poi.xwpf.usermodel.*;


import java.io.FileOutputStream;
import java.io.IOException;
import java.util.Map;

@SpringBootApplication
@MapperScan("com.jkglxt.www.mapper")
public class HealthManagementSystemApplication implements CommandLineRunner {

    public static void main(String[] args) {
        SpringApplication.run(HealthManagementSystemApplication.class, args);
    }

    // 这里添加启动类额外的方法
    @Override
    public void run(String... args) throws Exception {
        String swaggerUrl = "http://localhost:8080/v3/api-docs";
        RestTemplate restTemplate = new RestTemplate();
        Map apiDocs = restTemplate.getForObject(swaggerUrl, Map.class);

        XWPFDocument document = new XWPFDocument();
        XWPFParagraph paragraph = document.createParagraph();
        XWPFRun run = paragraph.createRun();
        run.setText("API Documentation");

        // Add API information
        for (Map.Entry entry : apiDocs.entrySet()) {
            paragraph = document.createParagraph();
            run = paragraph.createRun();
            run.setText(entry.getKey() + ": " + entry.getValue().toString());
        }

        // Save to file
        try (FileOutputStream out = new FileOutputStream("api-docs.docx")) {
            document.write(out);
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

---

- Thank you -